From f47f75ef049be4d1beb43f3c6451c23f2ccb4112 Mon Sep 17 00:00:00 2001
From: Timeless0911 <1604889533@qq.com>
Date: Mon, 6 Jan 2025 20:11:49 +0800
Subject: [PATCH 1/3] docs: introduce the different default values between
Rslib and Rsbuild
---
website/docs/en/config/rsbuild/output.mdx | 92 +++++++++++++++++++++++
website/docs/en/config/rsbuild/source.mdx | 6 +-
website/docs/zh/config/rsbuild/output.mdx | 92 +++++++++++++++++++++++
website/docs/zh/config/rsbuild/source.mdx | 6 +-
4 files changed, 194 insertions(+), 2 deletions(-)
diff --git a/website/docs/en/config/rsbuild/output.mdx b/website/docs/en/config/rsbuild/output.mdx
index ccfa5a8c7..d0b0123c8 100644
--- a/website/docs/en/config/rsbuild/output.mdx
+++ b/website/docs/en/config/rsbuild/output.mdx
@@ -32,6 +32,24 @@ Set the size threshold to inline static assets such as images and fonts.
Set the directory of the dist files. Rsbuild will output files to the corresponding subdirectory according to the file type.
+By default, Rslib sets `output.distPath` to:
+
+```ts
+const defaultDistPath = {
+ root: 'dist',
+ js: './',
+ jsAsync: './',
+ css: './',
+ cssAsync: './',
+ svg: 'static/svg',
+ font: 'static/font',
+ wasm: 'static/wasm',
+ image: 'static/image',
+ media: 'static/media',
+ assets: 'static/assets',
+};
+```
+
{/* ## output.emitAssets */}
{/* Control whether to emit static assets such as images, fonts, audio, video, etc. */}
@@ -44,16 +62,24 @@ Whether to emit CSS to the output bundles.
At build time, prevent some `import` dependencies from being packed into bundles in your code, and instead fetch them externally at runtime.
+In bundle mode, Rslib will automatically add the dependencies listed in the `dependencies`, `optionalDependencies`, and `peerDependencies` fields of `package.json` to `output.externals`. See [lib.autoExternal](/config/lib/auto-external) for more information.
+
+:::note
It is important to note that `output.externals` differs from [resolve.alias](/config/rsbuild/resolve#resolvealias). Check out [resolve.alias](/config/rsbuild/resolve#resolvealias) documentation for more information.
+:::
## output.filenameHash
Whether to add a hash value to the filename after the production build.
+Rslib sets `output.filenameHash` to `false` by default.
+
## output.filename
Sets the filename of dist files.
+By default, Rslib sets `output.filename` based on [format](/config/lib/format), see [autoExtension](/config/lib/auto-extension) for more information.
+
{/* ## output.injectStyles */}
{/* Whether to inject styles into DOM. */}
@@ -78,10 +104,74 @@ Whether to generate a manifest file that contains information of all assets, and
Configure whether to enable code minification in production mode, or to configure minimizer options.
+When `output.minify` is not specified, Rslib will use a sane default value.
+
+- When format is `esm`, `cjs` and `umd`, only dead code elimination and unused code elimination will be performed. The default value is:
+
+```ts
+export default defineConfig({
+ output: {
+ minify: {
+ js: true,
+ css: false,
+ jsOptions: {
+ minimizerOptions: {
+ mangle: false,
+ minify: false,
+ compress: {
+ defaults: false,
+ unused: true,
+ dead_code: true,
+ toplevel: true,
+ },
+ format: {
+ comments: 'some',
+ preserve_annotations: true,
+ },
+ },
+ },
+ },
+ },
+});
+```
+
+- When format is `mf`, since MF assets are loaded over the network, which means they will not be compressed by the application project. Therefore, they need to be minified in Rslib. The default value is:
+
+```ts
+export default defineConfig({
+ output: {
+ minify: {
+ js: true,
+ css: false,
+ jsOptions: {
+ minimizerOptions: {
+ mangle: false,
+ // Enable minification
+ minify: true,
+ compress: {
+ defaults: false,
+ unused: true,
+ dead_code: true,
+ // Avoid remoteEntry's global variable being tree-shaken
+ toplevel: false,
+ },
+ format: {
+ comments: 'some',
+ preserve_annotations: true,
+ },
+ },
+ },
+ },
+ },
+});
+```
+
## output.overrideBrowserslist
Specifies the range of target browsers that the project is compatible with.
+Rslib will generate `output.overrideBrowserslist` based on [syntax](/config/lib/syntax), see [ESX_TO_BROWSERSLIST](https://github.com/web-infra-dev/rslib/blob/8d65f3728d60254bcf1a8e24d72902ad79dae959/packages/core/src/utils/syntax.ts#L42-L153) to get the mapping value.
+
## output.polyfill
Through the `output.polyfill` option, you can control the injection mode of the polyfills.
@@ -98,6 +188,8 @@ Used to set whether to generate source map files, and which format of source map
Setting the build target of Rsbuild.
+Rslib sets `output.target` to `node` by default.
+
:::info
Check out the [Solution](/guide/solution/) to learn more about the build target.
:::
diff --git a/website/docs/en/config/rsbuild/source.mdx b/website/docs/en/config/rsbuild/source.mdx
index fb202fd6b..ce47d3455 100644
--- a/website/docs/en/config/rsbuild/source.mdx
+++ b/website/docs/en/config/rsbuild/source.mdx
@@ -13,13 +13,17 @@ Include additional files that should be treated as static assets.
Used to configure the decorators syntax.
+If `experimentalDecorators` is enabled in `tsconfig.json`, Rslib will set `source.decorators.version` to `legacy` by default.
+
## source.define
Replaces variables in your code with other values or expressions at compile time. This can be useful for allowing different behavior between development builds and production builds.
## source.entry
-Used to set the entry modules for building. In Rslib, the default value of `source.entry` is:
+Used to set the entry modules for building.
+
+In Rslib, the default value is:
- bundle mode: `src/index.(ts|js|tsx|jsx|mjs|cjs)`
- bundleless mode: `src/**`
diff --git a/website/docs/zh/config/rsbuild/output.mdx b/website/docs/zh/config/rsbuild/output.mdx
index fac06e202..75e76d398 100644
--- a/website/docs/zh/config/rsbuild/output.mdx
+++ b/website/docs/zh/config/rsbuild/output.mdx
@@ -28,6 +28,24 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';
设置构建产物的输出目录，Rsbuild 会根据产物的类型输出到对应的子目录下。
+Rslib 默认将 `output.distPath` 设置为：
+
+```ts
+const defaultDistPath = {
+ root: 'dist',
+ js: './',
+ jsAsync: './',
+ css: './',
+ cssAsync: './',
+ svg: 'static/svg',
+ font: 'static/font',
+ wasm: 'static/wasm',
+ image: 'static/image',
+ media: 'static/media',
+ assets: 'static/assets',
+};
+```
+
## output.emitCss
是否将 CSS 输出到产物中。
@@ -36,16 +54,24 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';
在构建时，防止将代码中某些 `import` 的依赖包打包到 bundle 中，而是在运行时再去从外部获取这些依赖。
+在 bundle 模式下，Rslib 会默认将 `package.json` 中 `dependencies`、`optionalDependencies` 和 `peerDependencies` 字段下的三方依赖添加到 `output.externals` 中, 查看 [lib.autoExternal](/config/lib/auto-external) 了解更多信息。
+
+:::note
需要注意的是，`output.externals` 与 [resolve.alias](/config/rsbuild/resolve#resolvealias) 有所不同。请查看 [resolve.alias](/config/rsbuild/resolve#resolvealias) 文档以了解更多信息。
+:::
## output.filenameHash
在生产模式构建后，是否在产物的文件名中添加 hash 值。
+Rslib 默认将 `output.filenameHash` 设置为 `false`。
+
## output.filename
设置构建产物的名称。
+Rslib 默认会根据 [format](/config/lib/format) 设置 `output.filename`，详情可查看 [autoExtension](/config/lib/auto-extension)。
+
## output.inlineScripts
用来控制是否用 `