docs: add mode config documentation (web-infra-dev#3157)

website/docs/en/config/_meta.json

@@ -4,6 +4,7 @@
     "name": "index",
     "label": "Overview"
   },
+  "mode",
   "environments",
   "plugins",
   {

website/docs/en/config/mode.mdx

@@ -0,0 +1,65 @@
+# mode
+
+- **Type:** `'production' | 'development' | 'none'`
+- **Version:** `>= 1.0.0`
+
+Specify the build mode for Rsbuild, as each mode has different default behavior and optimizations. For example, the `production` mode will compress code by default.
+
+The value of Rsbuild `mode` is also be passed to the [mode](https://rspack.dev/config/mode) configuration of Rspack.
+
+:::tip
+The value of `mode` does not affect the loading of `.env` files. Rsbuild supports the use of the `--env-mode` option to specify the env mode. See [env mode](/guide/advanced/env-vars#env-mode) for more details.
+:::
+
+## Default Values
+
+The default value of `mode` depends on the `process.env.NODE_ENV` environment variable:
+
+- If `NODE_ENV` is `production`, the default value is `production`.
+- If `NODE_ENV` is `development`, the default value is `development`.
+- If `NODE_ENV` has any other value, the default value is `none`.
+
+If you set the value of `mode`, the value of `NODE_ENV` will be ignored.
+
+```ts title="rsbuild.config.ts"
+export default {
+  mode: 'production',
+};
+```
+
+### Command Line
+
+When using Rsbuild's command line:
+
+- `rsbuild dev` will set the default values of `NODE_ENV` and `mode` to `development`.
+- `rsbuild build` and `rsbuild preview` will set the default values of `NODE_ENV` and `mode` to `production`.
+
+### JavaScript API
+
+When using Rsbuild's JavaScript API:
+
+- [rsbuild.startDevServer](/api/javascript-api/instance#rsbuildstartdevserver) and [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver) will set the default values of `NODE_ENV` and `mode` to `development`.
+- [rsbuild.build](/api/javascript-api/instance#rsbuildbuild) and [rsbuild.preview](/api/javascript-api/instance#rsbuildpreview) will set the default values of `NODE_ENV` and `mode` to `production`.
+
+## Development Mode
+
+If the value of `mode` is `development`:
+
+- Enable HMR and register the [HotModuleReplacementPlugin](https://rspack.dev/plugins/webpack/hot-module-replacement-plugin).
+- Generate JavaScript source maps, but do not generate CSS source maps. See [output.sourceMap](/config/output/source-map) for details.
+
+## Production Mode
+
+If the value of `mode` is `production`:
+
+- Enable JavaScript code minification and register the [SwcJsMinimizerRspackPlugin](https://rspack.dev/plugins/rspack/swc-js-minimizer-rspack-plugin).
+- Enable CSS code minification and register the [LightningCssMinimizerRspackPlugin](https://rspack.dev/plugins/rspack/lightning-css-minimizer-rspack-plugin).
+- Generated JavaScript and CSS filenames will have hash suffixes, see [output.filenameHash](/config/output/filename-hash).
+- Generated CSS Modules classnames will be shorter, see [cssModules.localIdentName](/config/output/css-modules#cssmoduleslocalidentname).
+- Do not generate JavaScript and CSS source maps, see [output.sourceMap](/config/output/source-map).
+
+## None Mode
+
+If the value of `mode` is `none`:
+
+- Do not enable any optimizations.

website/docs/zh/config/_meta.json

@@ -4,6 +4,7 @@
     "name": "index",
     "label": "Overview"
   },
+  "mode",
   "environments",
   "plugins",
   {

website/docs/zh/config/mode.mdx

@@ -0,0 +1,65 @@
+# mode
+
+- **类型：** `'production' | 'development' | 'none'`
+- **版本：** `>= 1.0.0`
+
+指定 Rsbuild 构建的模式，各个模式默认的行为和优化不同，比如 `production` 模式默认会压缩代码。
+
+Rsbuild `mode` 的值也会传递给 Rspack 的 [mode](https://rspack.dev/config/mode) 配置。
+
+:::tip
+`mode` 的值不会影响 `.env` 文件的加载，Rsbuild 支持使用 `--env-mode` 选项来指定 env 模式，详见 [env 模式](/guide/advanced/env-vars#env-模式)。
+:::
+
+## 默认值
+
+`mode` 的默认值取决于 `process.env.NODE_ENV` 环境变量：
+
+- 如果 `NODE_ENV` 为 `production`，则默认值为 `production`。
+- 如果 `NODE_ENV` 为 `development`，则默认值为 `development`。
+- 如果 `NODE_ENV` 为其他值，则默认值为 `none`。
+
+如果你设置了 `mode` 的值，则 `NODE_ENV` 的值会被忽略。
+
+```ts title="rsbuild.config.ts"
+export default {
+  mode: 'production',
+};
+```
+
+### 命令行
+
+当你使用 Rsbuild 的命令行时：
+
+- `rsbuild dev` 会将 `NODE_ENV` 和 `mode` 的默认值设置为 `development`。
+- `rsbuild build` 和 `rsbuild preview` 会将 `NODE_ENV` 和 `mode` 的默认值设置为 `production`。
+
+### JavaScript API
+
+当你使用 Rsbuild 的 JavaScript API 时：
+
+- [rsbuild.startDevServer](/api/javascript-api/instance#rsbuildstartdevserver) 和 [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver) 会将 `NODE_ENV` 和 `mode` 的默认值设置为 `development`。
+- [rsbuild.build](/api/javascript-api/instance#rsbuildbuild) 和 [rsbuild.preview](/api/javascript-api/instance#rsbuildpreview) 会将 `NODE_ENV` 和 `mode` 的默认值设置为 `production`。
+
+## Development 模式
+
+当 `mode` 的值为 `development` 时：
+
+- 开启 HMR，注册 [HotModuleReplacementPlugin](https://rspack.dev/plugins/webpack/hot-module-replacement-plugin)。
+- 生成 JavaScript 的 source map，不生成 CSS 的 source map，详见 [output.sourceMap](/config/output/source-map)。
+
+## Production 模式
+
+当 `mode` 的值为 `production` 时：
+
+- 开启 JavaScript 代码压缩，注册 [SwcJsMinimizerRspackPlugin](https://rspack.dev/plugins/rspack/swc-js-minimizer-rspack-plugin)。
+- 开启 CSS 代码压缩，注册 [LightningCssMinimizerRspackPlugin](https://rspack.dev/plugins/rspack/lightning-css-minimizer-rspack-plugin)。
+- 生成的 JavaScript 和 CSS 文件名会带有 hash 后缀，详见 [output.filenameHash](/config/output/filename-hash)。
+- 生成的 CSS Modules 类名更简短，详见 [cssModules.localIdentName](/config/output/css-modules#cssmoduleslocalidentname)。
+- 不生成 JavaScript 和 CSS 的 source map，详见 [output.sourceMap](/config/output/source-map)。
+
+## None 模式
+
+当 `mode` 的值为 `none` 时：
+
+- 不开启任何优化。