docs: configure Rslib

website/docs/en/config/rsbuild.mdx

@@ -1 +1 @@
-# Rsbuild 配置
+# Rsbuild Configuration

website/docs/en/guide/basic/cli.mdx

@@ -71,7 +71,7 @@ When you run the command `npx rslib inspect` in the project root directory, the
 ```text
 ➜ npx rslib inspect
 
-success Inspect config succeed, open following files to view the content:
+Inspect config succeed, open following files to view the content:
 
   - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs
   - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs
@@ -94,8 +94,6 @@ If the current project has multiple output formats, such as ESM artifact and CJS
 
 Inspect config succeed, open following files to view the content:
 
-success 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

website/docs/en/guide/basic/configure-rslib.mdx

@@ -1 +1,210 @@
 # 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.
+
+## Configuration Structure
+
+The configuration structure of Rslib looks like this:
+
+```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
+    {
+      // 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
+      output: {
+        // options for build outputs
+      },
+      source: {
+        // options for source code parsing and compilation
+      },
+      tools: {
+        // options for the low-level tools
+      },
+      plugins: [
+        // configure Rsbuild plugins
+      ],
+      // other independent Rsbuild configurations
+    },
+    {
+      // 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
+  },
+  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.
+
+- **[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.
+
+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
+
+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:
+
+- `rslib.config.mjs`
+- `rslib.config.ts`
+- `rslib.config.js`
+- `rslib.config.cjs`
+- `rslib.config.mts`
+- `rslib.config.cts`
+
+We recommend using the `.mjs` or `.ts` format for the configuration file and importing the `defineConfig` utility function from `@rslib/core`. It provides friendly TypeScript type hints and autocompletion, which can help you avoid errors in the configuration.
+
+For example, in `rslib.config.ts`, you can define the Rslib [syntax](/config/lib/syntax) configuration and the Rsbuild [output.target](https://rsbuild.dev/config/output/target#outputtarget) configuration:
+
+```ts title="rslib.config.ts"
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig({
+  lib: [
+    {
+      format: 'esm',
+      syntax: 'es2021',
+    },
+  ],
+  output: {
+    target: 'node',
+  },
+});
+```
+
+If you are developing a non-TypeScript project, you can use the `.mjs` format for the configuration file.
+
+:::tip
+
+When you use the `.ts`, `.mts`, and `.cts` extensions, Rslib will use [jiti](https://github.com/unjs/jiti) to load configuration files, providing interoperability between ESM and CommonJS. The behavior of module resolution differs slightly from the native behavior of Node.js.
+
+:::
+
+## Specify Config File
+
+Rslib CLI uses the `--config` option to specify the config file, which can be set to a relative path or an absolute path.
+
+For example, if you need to use the `rslib.prod.config.mjs` file when running `build`, you can add the following scripts to `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "build": "rslib build --config rslib.prod.config.mjs"
+  }
+}
+```
+
+You can also abbreviate the `--config` option to `-c`:
+
+```bash
+rslib build -c rslib.prod.config.mjs
+```
+
+## Using Environment Variables
+
+In the configuration file, you can use Node.js environment variables such as `process.env.NODE_ENV` to dynamically set different configurations:
+
+```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',
+    },
+  },
+});
+```
+
+## 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).
+
+You can also refer to the [Rsbuild Configuration](https://rsbuild.dev/config/index#config-overview) for checking the complete configuration items.
+
+## Configure Rspack
+
+Rslib is built on top of Rsbuild and Rsbuild supports directly modifying the Rspack configuration object and also supports modifying the built-in Rspack configuration of Rsbuild through `rspack-chain`. This means you can configure Rspack related configurations in an Rslib project as well.
+
+For more details, refer to [Configure Rspack](https://rsbuild.dev/guide/basic/configure-rspack).
+
+## Configuration Debug
+
+You can enable Rslib's debug mode by adding the `DEBUG=rsbuild` environment variable when executing a build. It will display the final Rsbuild/Rspack configuration after processing by Rslib.
+
+```bash
+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.
+
+```
+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
+```
+
+- Open the generated `/dist/.rsbuild/rsbuild.config.esm.mjs` file to see the complete content of the Rsbuild config.
+- Open the generated `/dist/.rsbuild/rspack.config.esm.mjs` file to see the complete content of the Rspack config.