docs: translate configure-rslib (#528)

chenjiahan · Timeless0911 · web-flow · commit 6a834d143228 · 2024-12-06T13:37:22.000+08:00
Co-authored-by: Timeless0911 &lt;50201324+Timeless0911@users.noreply.github.com&gt;
diff --git a/website/docs/en/guide/basic/configure-rslib.mdx b/website/docs/en/guide/basic/configure-rslib.mdx
@@ -1,94 +1,72 @@
 # Configure Rslib
 
-Rslib provides a wide range of configuration options and sets a common default value for each option, which can meet the requirements of most use cases. Therefore, in most cases, you can use Rslib out of the box with few configurations.
-
-If you need to customize build behaviors, you can read the following sections to learn about the configuration options and its usage.
+Rslib's configuration is based on Rsbuild, which means that you can use all of Rsbuild configurations, as well as the `lib` configuration specific to Rslib.
 
 ## Configuration Structure
 
-The configuration structure of Rslib looks like this:
+Rslib provides the `lib` option to configure the library outputs. It is an array, and each object is used to describe a format of the output.
+
+For example, output ESM and CJS formats, and use `es2021` syntax:
+
+```js title="rslib.config.mjs"
+export default {
+  lib: [
+    { format: 'esm', syntax: 'es2021' },
+    { format: 'cjs', syntax: 'es2021' },
+  ],
+};
+```
+
+### Common Rsbuild Configurations
+
+You can set common Rsbuild configurations outside the `lib` field, which will be inherited by each configuration object inside the `lib` field.
+
+For example, set the [output.target](/config/rsbuild/output#outputtarget) of Rsbuild to `web`, which will affect the output of all `lib` configuration objects:
+
+```js title="rslib.config.mjs"
+export default {
+  lib: [
+    { format: 'esm', syntax: 'es2021' },
+    { format: 'cjs', syntax: 'es2021' },
+  ],
+  output: {
+    target: 'web',
+  },
+};
+```
+
+### Separate Rsbuild Configurations
+
+In the `lib` field, you can set separate Rsbuild configurations for each output format, which will override the common Rsbuild configurations outside the `lib` field.
+
+For example, separately set the [output.target](/config/rsbuild/output#outputtarget) of the ESM output to `web`:
 
 ```js title="rslib.config.mjs"
 export default {
-  // Array of Lib configurations.
-  // Each object represents a set of independent configurations for each output format.
-  // Distinct configurations can be specified in each object, which is a superset of Rsbuild configurations along with Rslib's specific configurations.
   lib: [
-    // The first set of Lib configurations
+    // The target of the ESM output is `web`
     {
-      // Independent Rslib specific configurations
-      format: 'esm', // options for the output format of JavaScript files
-      bundle: true, // options for the build type
-      autoExtension: true, // options for the extensions of JavaScript files
-      syntax: 'esnext', // options for the target syntax
-      externalHelpers: false, // options for externalizing helper functions
-      umdName: 'RslibUmdExample', // options for the export name of the UMD library
-      autoExternal: {
-        // options for automatically externalizing third-party dependencies
-      },
-      redirect: {
-        // options for redirecting import paths
-      },
-      dts: {
-        // options for generating TypeScript declaration files
-      },
-      shims: {
-        // options for compatibility shims
-      },
-      banner: {
-        // options for the file banner
-      },
-      footer: {
-        // options for the file footer
-      },
-      // Independent Rsbuild configurations
+      format: 'esm',
       output: {
-        // options for build outputs
-      },
-      source: {
-        // options for source code parsing and compilation
-      },
-      tools: {
-        // options for the low-level tools
+        target: 'web',
       },
-      plugins: [
-        // configure Rsbuild plugins
-      ],
-      // other independent Rsbuild configurations
     },
+    // The CJS output inherits the common configuration and target is `node`
     {
-      // The second set of Lib configurations
       format: 'cjs',
-      // ... other independent Rslib specific configurations and Rsbuild configurations
     },
-    // ... Additional sets of Lib configurations (if needed)
   ],
-  // Shared Rsbuild configurations
   output: {
-    // options for build outputs
-  },
-  source: {
-    // options for source code parsing and compilation
-  },
-  tools: {
-    // options for the low-level tools
+    target: 'node',
   },
-  plugins: [
-    // configure Rsbuild plugins
-  ],
-  // ... other Rsbuild configurations
 };
 ```
 
-The configuration file exports a default object that includes a `lib` array and shared Rsbuild configuration options. You can find detailed descriptions of all configs on the [Configure Overview](/config/) page.
+Rslib will generate the [environments](https://rsbuild.dev/config/environments) configuration of Rsbuild internally, please refer to [Configuration Debug](#configuration-debug) to view the final generated configuration.
 
-- **[Lib Configurations](/config/lib/) (at least one object is required)**: The `lib` array contains multiple objects, each representing a set of independent configurations that will generate different outputs. Each object within the `lib` array can specify unique configurations, which is a superset of Rsbuild
-  configurations along with Rslib's specific configurations.
-- **Shared [Rsbuild Configurations](/config/rsbuild/) (optional)**: Outside the `lib` array, there are shared Rsbuild configuration options that will be deep merged with independent Rsbuild configuration of each `lib` configuration object.
+You can also refer to the [Configuration Overview](/config/) page to view the detailed introduction of all configurations.
 
-Rslib generates corresponding Rsbuild [environments](https://rsbuild.dev/guide/advanced/environments) configurations based on the multiple build configurations of different output formats. You can view the final generated configurations through the [configuration debug](#configuration-debug) documentation.
-
-## Configuration Usage
+## Configuration File
 
 When you use the CLI of Rslib, Rslib will automatically read the configuration file in the root directory of the current project and resolve it in the following order:
 
@@ -173,11 +151,10 @@ export default defineConfig({
 
 ## Configure Rsbuild
 
-In Rslib project, you can configure Rsbuild related configurations in both `lib` configuration object and shared configuration section.
-
-Common-used Rsbuild configurations in library development are listed at [Rsbuild Configuration](/config/rsbuild/).
+Rslib allows you to use most of the Rsbuild configurations. Currently, the `environments` config is not supported because it is generated internally by Rslib.
 
-You can also refer to the [Rsbuild Configuration](https://rsbuild.dev/config/index#config-overview) for checking the complete configuration items.
+- Refer to [Rsbuild Configuration](/config/rsbuild/) for common Rsbuild configurations.
+- Refer to [Rsbuild Documentation](https://rsbuild.dev/config/index#config-overview) for all Rsbuild configurations.
 
 ## Configure Rspack
 
@@ -195,7 +172,7 @@ DEBUG=rsbuild pnpm build
 
 In debug mode, Rslib will write the Rsbuild / Rspack config to the dist directory, which is convenient for developers to view and debug.
 
-Below is an example of a configuration for Rslib that builds both CJS and ESM output.
+Here is an example of a library that sets both CJS and ESM formats:
 
 ```
 Inspect config succeed, open following files to view the content:
diff --git a/website/docs/zh/guide/basic/configure-rslib.mdx b/website/docs/zh/guide/basic/configure-rslib.mdx
@@ -1 +1,187 @@
 # 配置 Rslib
+
+Rslib 的配置是基于 Rsbuild 扩展的，这意味着你可以使用 Rsbuild 的所有配置，以及 Rslib 特有的 `lib` 配置。
+
+## 配置结构
+
+Rslib 提供了 `lib` 选项来配置库产物，它是一个数组，每个对象用于描述一种输出格式。
+
+例如，输出 ESM 和 CJS 两种格式的产物，并使用 `es2021` 语法：
+
+```js title="rslib.config.mjs"
+export default {
+  lib: [
+    { format: 'esm', syntax: 'es2021' },
+    { format: 'cjs', syntax: 'es2021' },
+  ],
+};
+```
+
+### 公共的 Rsbuild 配置
+
+在 `lib` 字段外部，你可以设置公共的 Rsbuild 配置，这些配置将被 `lib` 内的每个配置对象继承。
+
+例如，设置 Rsbuild 的 [output.target](/config/rsbuild/output#outputtarget) 为 `web`，这会影响所有 `lib` 配置对象的输出：
+
+```js title="rslib.config.mjs"
+export default {
+  lib: [
+    { format: 'esm', syntax: 'es2021' },
+    { format: 'cjs', syntax: 'es2021' },
+  ],
+  output: {
+    target: 'web',
+  },
+};
+```
+
+### 单独的 Rsbuild 配置
+
+在 `lib` 字段内部，你可以为每种输出格式设置单独的 Rsbuild 配置，这些配置将覆盖外部的公共 Rsbuild 配置。
+
+例如，单独设置 ESM 产物的 [output.target](/config/rsbuild/output#outputtarget) 为 `web`：
+
+```js title="rslib.config.mjs"
+export default {
+  lib: [
+    // ESM 产物的 target 为 `web`
+    {
+      format: 'esm',
+      output: {
+        target: 'web',
+      },
+    },
+    // CJS 产物继承了公共配置，target 为 `node`
+    {
+      format: 'cjs',
+    },
+  ],
+  output: {
+    target: 'node',
+  },
+};
+```
+
+Rslib 会在内部生成 Rsbuild 的 [environments](https://rsbuild.dev/zh/config/environments) 配置，请参考 [调试配置](#调试配置) 来查看最终生成的配置。
+
+你也可以在 [配置概览](/config/) 页面查看所有配置的详细介绍。
+
+## 配置文件
+
+当你使用 Rslib 的 CLI 命令时，Rslib 会自动读取当前项目根目录下的配置文件，按照以下顺序进行解析：
+
+- `rslib.config.mjs`
+- `rslib.config.ts`
+- `rslib.config.js`
+- `rslib.config.cjs`
+- `rslib.config.mts`
+- `rslib.config.cts`
+
+我们推荐使用 `.mjs` 或 `.ts` 格式的配置文件，并从 `@rslib/core` 中导入 `defineConfig` 工具函数, 它提供了友好的 TypeScript 类型推导和自动补全，可以帮助你避免配置中的错误。
+
+比如在 `rslib.config.ts` 中，你可以定义 Rslib 的 [syntax](/config/lib/syntax) 配置和 Rsbuild 的 [output.target](https://rsbuild.dev/config/output/target#outputtarget) 配置：
+
+```ts title="rslib.config.ts"
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig({
+  lib: [
+    {
+      format: 'esm',
+      syntax: 'es2021',
+    },
+  ],
+  output: {
+    target: 'node',
+  },
+});
+```
+
+如果你在开发一个非 TypeScript 项目，可以使用 `.mjs` 格式的配置文件。
+
+:::tip
+
+当你使用 `.ts`, `.mts` 和 `.cts` 后缀时，Rslib 会使用 [jiti](https://github.com/unjs/jiti) 来加载配置文件，提供 ESM 与 CommonJS 的互操作性，模块解析的行为与 Node.js 原生行为存在一定差异。
+
+:::
+
+## 指定配置文件
+
+Rslib CLI 通过 `--config` 选项来指定配置文件，可以设置为相对路径或绝对路径。
+
+例如，你需要在执行 `build` 命令时使用 `rslib.prod.config.mjs` 文件，可以在 `package.json` 中添加如下配置：
+
+```json title="package.json"
+{
+  "scripts": {
+    "build": "rslib build --config rslib.prod.config.mjs"
+  }
+}
+```
+
+你也可以将 `--config` 选项缩写为 `-c`：
+
+```bash
+rslib build -c rslib.prod.config.mjs
+```
+
+## 使用环境变量
+
+在配置文件中，你可以使用 `process.env.NODE_ENV` 等 Node.js 环境变量，来动态写入不同的配置：
+
+```ts title="rslib.config.ts"
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig({
+  lib: [
+    {
+      format: 'esm',
+    },
+  ],
+  source: {
+    alias: {
+      '@request':
+        process.env.NODE_ENV === 'development'
+          ? './src/request.dev.js'
+          : './src/request.prod.js',
+    },
+  },
+});
+```
+
+## 配置 Rsbuild
+
+Rslib 允许你使用绝大部分的 Rsbuild 配置。目前不支持使用 `environments` 配置，因为该字段会在 Rslib 内部生成。
+
+- 参考 [Rsbuild 配置](/config/rsbuild/) 了解常用的 Rsbuild 配置。
+- 参考 [Rsbuild 文档](https://rsbuild.dev/config/index#config-overview) 了解所有 Rsbuild 配置。
+
+## 配置 Rspack
+
+Rslib 基于 Rsbuild 构建，Rsbuild 支持直接修改 Rspack 配置对象，也支持通过 `rspack-chain` 修改 Rsbuild 内置的 Rspack 配置。这意味着你可以在 Rslib 项目中配置 Rspack 相关配置。
+
+详情请参考 [配置 Rspack](https://rsbuild.dev/guide/basic/configure-rspack)。
+
+## 调试配置
+
+在执行构建时，你可以通过添加 `DEBUG=rsbuild` 环境变量来启用 Rslib 的调试模式，它会在 Rslib 处理后显示最终的 Rsbuild 和 Rspack 配置。
+
+```bash
+DEBUG=rsbuild pnpm build
+```
+
+在调试模式下，Rslib 会将 Rsbuild 和 Rspack 配置写入到 `dist` 目录下，方便开发者查看和调试。
+
+以下是一个例子，这个库设置了 CJS 和 ESM 两种输出格式：
+
+```
+Inspect config succeed, open following files to view the content:
+
+  - Rsbuild Config (esm): /project/dist/.rsbuild/rsbuild.config.esm.mjs
+  - Rsbuild Config (cjs): /project/dist/.rsbuild/rsbuild.config.cjs.mjs
+  - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs
+  - Rspack Config (cjs): /project/dist/.rsbuild/rspack.config.cjs.mjs
+```
+
+- 打开生成的 `/dist/.rsbuild/rsbuild.config.esm.mjs` 文件，即可查看 Rsbuild 配置的完整内容。
+- 打开生成的 `/dist/.rsbuild/rspack.config.esm.mjs` 文件，即可查看 Rspack 配置的完整内容。
