docs: introduce the different default values between Rslib and Rsbuild (#651)

Co-authored-by: Wei <[email protected]>

Author: Timeless0911

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 <RsbuildDocBadge path="/config/output/emit-assets" text="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 <RsbuildDocBadge path="/config/output/filename-hash" text="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 <RsbuildDocBadge path="/config/output/filename" text="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 <RsbuildDocBadge path="/config/output/inject-styles" text="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 <RsbuildDocBadge path="/config/output/override-browserslist" text="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 <RsbuildDocBadge path="/config/output/polyfill" text="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.
 :::

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](https://www.typescriptlang.org/tsconfig/#experimentalDecorators) is enabled in `tsconfig.json`, Rslib will set `source.decorators.version` to `legacy` by default.
+
 ## source.define <RsbuildDocBadge path="/config/source/define" text="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 <RsbuildDocBadge path="/config/source/entry" text="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/**`

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 <RsbuildDocBadge path="/config/output/emit-css" text="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 <RsbuildDocBadge path="/config/output/filename-hash" text="output.filenameHash" />
 
 在生产模式构建后，是否在产物的文件名中添加 hash 值。
 
+Rslib 默认将 `output.filenameHash` 设置为 `false`。
+
 ## output.filename <RsbuildDocBadge path="/config/output/filename" text="output.filename" />
 
 设置构建产物的名称。
 
+Rslib 默认会根据 [format](/config/lib/format) 设置 `output.filename`，详情可查看 [autoExtension](/config/lib/auto-extension)。
+
 ## output.inlineScripts <RsbuildDocBadge path="/config/output/inline-scripts" text="output.inlineScripts" />
 
 用来控制是否用 `<script>` 标签将产物中的 script 文件（.js 文件）inline 到 HTML 中。
@@ -66,10 +92,74 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';
 
 用于设置是否在生产模式下开启代码压缩，或是配置压缩工具的选项。
 
+在未指定 `output.minify` 时，Rslib 会使用一个合理的默认值。
+
+- 在 format 为 `esm`, `cjs` 以及 `umd` 时，只会执行死代码消除和未使用代码消除，默认值为：
+
+```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,
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+- 在 format 为 `mf` 时，由于 MF 资源通过网络加载，这意味着它们不会被应用项目压缩。因此，需要在 Rslib 中对它们进行压缩。默认值为：
+
+```ts
+export default defineConfig({
+  output: {
+    minify: {
+      js: true,
+      css: false,
+      jsOptions: {
+        minimizerOptions: {
+          mangle: false,
+          // 启用压缩
+          minify: true,
+          compress: {
+            defaults: false,
+            unused: true,
+            dead_code: true,
+            // 避免 remoteEntry 的全局变量被 tree-shaking
+            toplevel: false,
+          },
+          format: {
+            comments: 'some',
+            preserve_annotations: true,
+          },
+        },
+      },
+    },
+  },
+});
+```
+
 ## output.overrideBrowserslist <RsbuildDocBadge path="/config/output/override-browserslist" text="output.overrideBrowserslist" />
 
 指定项目兼容的目标浏览器范围。
 
+Rslib 默认会根据 [syntax](/config/lib/syntax) 生成 `output.overrideBrowserslist`，查看 [ESX_TO_BROWSERSLIST](https://github.com/web-infra-dev/rslib/blob/8d65f3728d60254bcf1a8e24d72902ad79dae959/packages/core/src/utils/syntax.ts#L42-L153) 获取映射值。
+
 ## output.polyfill <RsbuildDocBadge path="/config/output/polyfill" text="output.polyfill" />
 
 控制 polyfills 的注入方式。
@@ -86,6 +176,8 @@ Rsbuild 的 `output.polyfill` 会将 polyfills 注入到全局作用域中，这
 
 用于设置 Rsbuild 的构建产物类型。
 
+Rslib 默认将 `output.target` 设置为 `node`。
+
 :::info
 请查看 [解决方案](/guide/solution/) 了解更多关于构建产物的信息。
 :::

website/docs/zh/config/rsbuild/source.mdx

@@ -12,13 +12,17 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';
 
 用于配置装饰器语法。
 
+如果在 `tsconfig.json` 中启用了 [experimentalDecorators](https://www.typescriptlang.org/tsconfig/#experimentalDecorators)，Rslib 会默认将 `source.decorators.version` 设置为 `legacy`。
+
 ## source.define <RsbuildDocBadge path="/config/source/define" text="source.define" />
 
 构建时将代码中的变量替换成其它值或者表达式，可以用于在代码逻辑中区分开发模式与生产模式等场景。
 
 ## source.entry <RsbuildDocBadge path="/config/source/entry" text="source.entry" />
 
-用于设置构建的入口模块。在 Rslib 中，`source.entry` 的默认值为：
+用于设置构建的入口模块。
+
+在 Rslib 中，默认值为：
 
 - bundle 模式：`src/index.(ts|js|tsx|jsx|mjs|cjs)`
 - bundleless 模式：`src/**`