From aea2b874f51cfcf0a595ed10537945db73b39e65 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 9 Oct 2026 14:04:42 +0800
Subject: [PATCH 1/9] docs: explain shared configuration APIs and test
 inheritance

---
 website/docs/en/guide/api-reference.mdx | 65 +++++++++++++++++++++++++
 website/docs/en/guide/testing.mdx       | 42 ++++++++++++++++
 website/docs/zh/guide/api-reference.mdx | 65 +++++++++++++++++++++++++
 website/docs/zh/guide/testing.mdx       | 42 ++++++++++++++++
 4 files changed, 214 insertions(+)

diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx
index 4a28006e..740bb290 100644
--- a/website/docs/en/guide/api-reference.mdx
+++ b/website/docs/en/guide/api-reference.mdx
@@ -11,6 +11,7 @@ Rstack CLI provides a unified configuration API and re-exports the public APIs o
 | Import path              | Contents                                          | Use case                                |
 | ------------------------ | ------------------------------------------------- | --------------------------------------- |
 | `rstack`                 | Rstack CLI configuration API                      | Register tool configurations            |
+| `rstack/config`          | Configuration loader and its types                | Load shared and project configurations  |
 | `rstack/app`             | Public APIs from `@rsbuild/core`                  | Build applications and extend Rsbuild   |
 | `rstack/lib`             | Public APIs from `@rslib/core`                    | Build libraries and extend Rslib        |
 | `rstack/test`            | Public APIs from `@rstest/core`                   | Write tests and configure test projects |
@@ -25,6 +26,70 @@ Rstack CLI provides a unified configuration API and re-exports the public APIs o
 
 Import `define` from `rstack` to register tool configurations in `rstack.config.ts`; see [Configuration APIs](./configuration#configuration-apis) for details.
 
+### `define.extends()` \{#define-extends}
+
+Inherits shared configurations before applying the project's own settings:
+
+```ts
+import { define } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+define.extends([sharedConfig]);
+```
+
+- **Type:** `(configs: readonly RstackConfig[]) => void`
+- Pass an array of configuration objects. If a preset is a function, call it first and pass the returned object.
+- Call at most once per configuration load. An empty array still counts as a call.
+- Shared configurations are applied from left to right, followed by the project's `define.*()` settings, regardless of call order.
+
+See [Shared configurations](./configuration#shared-configurations) for nested inheritance, merge rules, and examples.
+
+### `RstackConfig`
+
+Use this type to define a shared configuration. All fields are optional: `app`, `lib`, `doc`, `test`, `lint`, `fmt`, and `staged` accept the same values as their corresponding `define.*()` APIs. Add `extends`, typed as `readonly RstackConfig[]`, to inherit other shared configurations.
+
+```ts
+import type { RstackConfig } from 'rstack';
+
+export const sharedConfig: RstackConfig = {
+  fmt: {
+    singleQuote: true,
+  },
+};
+```
+
+## Loading configurations
+
+### `loadRstackConfig()` \{#loadrstackconfig}
+
+Import `loadRstackConfig` from `rstack/config` to load configurations programmatically:
+
+```ts
+import { loadRstackConfig } from 'rstack/config';
+
+const { configs, filePath, dependencies } = await loadRstackConfig({
+  cwd: process.cwd(),
+  configFilePath: './rstack.config.ts',
+});
+```
+
+Both options are optional:
+
+- `cwd`: the directory used to search for a configuration file and resolve relative configuration file paths. Defaults to the current working directory.
+- `configFilePath`: a relative or absolute configuration file path. If omitted, uses the CLI's `--config` path when set; otherwise, searches for the [default configuration file names](./configuration#configuration-file) in `cwd`.
+
+The returned object contains:
+
+- `configs`: tool configuration definitions that include both shared and project settings. Tools with no configuration are omitted.
+- `filePath`: the loaded configuration file's path, or `null` if no file was found.
+- `dependencies`: the configuration's dependencies, as reported by the loader.
+
+The loader leaves configuration functions unevaluated. It may also return an async function for a tool whose inputs were all objects, so those objects can be merged when the tool is needed.
+
+When using the result, resolve each definition with the parameters its tool expects, then follow that tool's setup and execution steps. Rstack's automatic test inheritance and formatting normalization still need to run at that stage. A `staged` function is a task generator: call it with the staged file names when running tasks.
+
+`rstack/config` also exports the `Configs`, `LoadedRstackConfig`, and `LoadRstackConfigOptions` types.
+
 ## Re-exports
 
 The tool-specific subpaths below re-export the public APIs from their corresponding core packages. Using these entry points keeps imports unified and APIs aligned with the tool versions integrated by Rstack CLI.
diff --git a/website/docs/en/guide/testing.mdx b/website/docs/en/guide/testing.mdx
index db90404c..fdeeec94 100644
--- a/website/docs/en/guide/testing.mdx
+++ b/website/docs/en/guide/testing.mdx
@@ -107,6 +107,48 @@ define.test({
 
 For multiple projects, setting `extends` on the root `define.test()` configuration disables automatic inheritance for every project. Setting it on an inline project disables inheritance only for that project.
 
+### Shared test configurations
+
+A [shared configuration](./configuration#shared-configurations) can provide both build and test settings. Rstack combines these with the project's settings before deciding whether tests should inherit the build configuration.
+
+First, Rstack merges the test settings with `mergeRstestConfig`. It then checks `extends` and `projects` in the merged result. Tests that need automatic inheritance use the merged App configuration, or the merged Lib configuration if no App configuration is defined.
+
+`define.extends()` and Rstest's `test.extends` serve different purposes: the former shares settings across tools; the latter controls Rstest's own configuration inheritance.
+
+```ts title="shared.ts"
+import type { RstackConfig } from 'rstack';
+
+export const sharedConfig: RstackConfig = {
+  app: {
+    resolve: {
+      alias: {
+        '@': './src',
+      },
+    },
+  },
+  test: {
+    retry: 2,
+  },
+};
+```
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+define.extends([sharedConfig]);
+
+define.test({
+  testEnvironment: 'happy-dom',
+});
+```
+
+Tests run in happy-dom with `retry: 2` and inherit the shared App configuration's `@` alias. There is no need to call `define.app()` in the project.
+
+To disable automatic inheritance, set `extends` explicitly in the test configuration. This also works in a shared configuration: if the merged test settings contain `extends`, even as `extends: undefined`, automatic inheritance is disabled.
+
+For multiple projects, Rstack checks the merged inline projects individually. External projects specified by strings still load their own configurations. If no project needs automatic inheritance, Rstack skips the App and Lib configuration functions.
+
 ## Multiple projects
 
 Set Rstest's [`projects`](https://rstest.rs/config/test/projects) option to run multiple test configurations together. Entries can be inline projects or strings that Rstest resolves as external projects.
diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx
index 16c373fc..6ccd0761 100644
--- a/website/docs/zh/guide/api-reference.mdx
+++ b/website/docs/zh/guide/api-reference.mdx
@@ -11,6 +11,7 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
 | 导入路径                 | 内容                                      | 使用场景                 |
 | ------------------------ | ----------------------------------------- | ------------------------ |
 | `rstack`                 | Rstack CLI 配置 API                       | 注册各项工具配置         |
+| `rstack/config`          | 配置加载器及其类型                        | 加载公共配置和项目配置   |
 | `rstack/app`             | `@rsbuild/core` 的公开 API                | 构建应用及扩展 Rsbuild   |
 | `rstack/lib`             | `@rslib/core` 的公开 API                  | 构建库及扩展 Rslib       |
 | `rstack/test`            | `@rstest/core` 的公开 API                 | 编写测试及配置测试项目   |
@@ -25,6 +26,70 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
 
 从 `rstack` 导入 `define`，用于在 `rstack.config.ts` 中注册各项工具配置；详细用法请参阅[配置 API](./configuration#configuration-apis)。
 
+### `define.extends()` \{#define-extends}
+
+继承公共配置，再应用项目自己的配置：
+
+```ts
+import { define } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+define.extends([sharedConfig]);
+```
+
+- **类型：** `(configs: readonly RstackConfig[]) => void`
+- 传入配置对象数组。如果预设是函数，请先调用它，再传入返回的对象。
+- 每次加载配置时最多调用一次，传入空数组也算一次调用。
+- 先从左到右应用公共配置，再应用项目的 `define.*()` 配置，与调用顺序无关。
+
+嵌套继承、合并规则和示例请参阅[公共配置](./configuration#shared-configurations)。
+
+### `RstackConfig`
+
+使用这个类型定义公共配置。所有字段均为可选：`app`、`lib`、`doc`、`test`、`lint`、`fmt` 和 `staged` 的用法与对应的 `define.*()` API 一致。需要继承其他公共配置时，可以添加类型为 `readonly RstackConfig[]` 的 `extends` 字段。
+
+```ts
+import type { RstackConfig } from 'rstack';
+
+export const sharedConfig: RstackConfig = {
+  fmt: {
+    singleQuote: true,
+  },
+};
+```
+
+## 加载配置 \{#loading-configurations}
+
+### `loadRstackConfig()` \{#loadrstackconfig}
+
+从 `rstack/config` 导入 `loadRstackConfig`，以编程方式加载配置：
+
+```ts
+import { loadRstackConfig } from 'rstack/config';
+
+const { configs, filePath, dependencies } = await loadRstackConfig({
+  cwd: process.cwd(),
+  configFilePath: './rstack.config.ts',
+});
+```
+
+两个选项均可省略：
+
+- `cwd`：用于查找配置文件和解析相对配置文件路径的目录，默认为当前工作目录。
+- `configFilePath`：配置文件的相对或绝对路径。省略时，优先使用 CLI 的 `--config` 路径；如果未设置，则在 `cwd` 中查找[默认配置文件名](./configuration#configuration-file)。
+
+返回对象包含：
+
+- `configs`：包含公共配置和项目配置的工具配置定义。未配置的工具不会出现在该对象中。
+- `filePath`：加载的配置文件路径，未找到文件时为 `null`。
+- `dependencies`：加载器报告的配置依赖。
+
+加载器不会执行配置函数。即使某个工具的配置全部以对象形式传入，返回的字段也可能是异步函数，以便在需要该工具时再合并这些对象。
+
+使用返回结果时，需要按各工具的要求传入参数、解析配置，再执行相应的初始化和运行流程。Rstack 的测试自动继承和格式化配置标准化也需要在这个阶段完成。`staged` 函数用于生成任务，应在运行任务时传入暂存文件名。
+
+`rstack/config` 还导出 `Configs`、`LoadedRstackConfig` 和 `LoadRstackConfigOptions` 类型。
+
 ## 重导出 \{#re-exports}
 
 以下工具子路径均会重导出对应 core 包的公开 API。通过这些入口导入，可以统一依赖入口，并确保 API 与 Rstack CLI 集成的工具版本匹配。
diff --git a/website/docs/zh/guide/testing.mdx b/website/docs/zh/guide/testing.mdx
index 43474a71..961cdf51 100644
--- a/website/docs/zh/guide/testing.mdx
+++ b/website/docs/zh/guide/testing.mdx
@@ -107,6 +107,48 @@ define.test({
 
 使用多项目配置时，在 `define.test()` 根配置中设置 `extends` 会关闭所有项目的自动继承；在某个内联项目中设置 `extends` 则只会关闭该项目的自动继承。
 
+### 公共测试配置 \{#shared-test-configurations}
+
+[公共配置](./configuration#shared-configurations) 可以同时提供构建和测试配置。Rstack 会先将它们与项目配置合并，再判断测试是否需要继承构建配置。
+
+Rstack 首先使用 `mergeRstestConfig` 合并测试配置，再检查合并结果中的 `extends` 和 `projects`。需要自动继承的测试会使用合并后的 App 配置；没有定义 App 配置时，则使用合并后的 Lib 配置。
+
+`define.extends()` 用于在多个工具之间共享配置，Rstest 的 `test.extends` 则控制测试配置自身的继承，两者用途不同。
+
+```ts title="shared.ts"
+import type { RstackConfig } from 'rstack';
+
+export const sharedConfig: RstackConfig = {
+  app: {
+    resolve: {
+      alias: {
+        '@': './src',
+      },
+    },
+  },
+  test: {
+    retry: 2,
+  },
+};
+```
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+define.extends([sharedConfig]);
+
+define.test({
+  testEnvironment: 'happy-dom',
+});
+```
+
+测试会在 happy-dom 中运行，使用 `retry: 2`，并继承公共 App 配置中的 `@` 别名。项目中无需再调用 `define.app()`。
+
+如果要关闭自动继承，请在测试配置中显式设置 `extends`。在公共配置中设置也同样有效：只要合并后的测试配置包含 `extends`，即使值为 `undefined`，自动继承也会关闭。
+
+使用多项目配置时，Rstack 会逐一检查合并后的内联项目。字符串形式的外部项目仍独立加载自己的配置。如果所有项目都不需要自动继承，Rstack 就会跳过 App 和 Lib 配置函数。
+
 ## 多项目 \{#multiple-projects}
 
 通过 Rstest 的 [`projects`](https://rstest.rs/zh/config/test/projects) 选项可以同时运行多套测试配置。每一项既可以是内联项目，也可以是由 Rstest 解析为外部项目的字符串。

From aeb8fe88085fd1eab37aa50485bfd84f734ea728 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 9 Oct 2026 16:55:35 +0800
Subject: [PATCH 2/9] docs: split config loader reference and simplify extends
 API

---
 website/docs/en/guide/api-reference.mdx | 49 ++-----------------------
 website/docs/zh/guide/api-reference.mdx | 49 ++-----------------------
 2 files changed, 6 insertions(+), 92 deletions(-)

diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx
index 740bb290..61c01c9c 100644
--- a/website/docs/en/guide/api-reference.mdx
+++ b/website/docs/en/guide/api-reference.mdx
@@ -11,7 +11,6 @@ Rstack CLI provides a unified configuration API and re-exports the public APIs o
 | Import path              | Contents                                          | Use case                                |
 | ------------------------ | ------------------------------------------------- | --------------------------------------- |
 | `rstack`                 | Rstack CLI configuration API                      | Register tool configurations            |
-| `rstack/config`          | Configuration loader and its types                | Load shared and project configurations  |
 | `rstack/app`             | Public APIs from `@rsbuild/core`                  | Build applications and extend Rsbuild   |
 | `rstack/lib`             | Public APIs from `@rslib/core`                    | Build libraries and extend Rslib        |
 | `rstack/test`            | Public APIs from `@rstest/core`                   | Write tests and configure test projects |
@@ -28,21 +27,11 @@ Import `define` from `rstack` to register tool configurations in `rstack.config.
 
 ### `define.extends()` \{#define-extends}
 
-Inherits shared configurations before applying the project's own settings:
+Inherits shared configurations.
 
-```ts
-import { define } from 'rstack';
-import { sharedConfig } from './shared.ts';
-
-define.extends([sharedConfig]);
-```
+**Type:** `(configs: readonly RstackConfig[]) => void`
 
-- **Type:** `(configs: readonly RstackConfig[]) => void`
-- Pass an array of configuration objects. If a preset is a function, call it first and pass the returned object.
-- Call at most once per configuration load. An empty array still counts as a call.
-- Shared configurations are applied from left to right, followed by the project's `define.*()` settings, regardless of call order.
-
-See [Shared configurations](./configuration#shared-configurations) for nested inheritance, merge rules, and examples.
+See [Shared configurations](./configuration#shared-configurations) for usage and merge rules.
 
 ### `RstackConfig`
 
@@ -58,38 +47,6 @@ export const sharedConfig: RstackConfig = {
 };
 ```
 
-## Loading configurations
-
-### `loadRstackConfig()` \{#loadrstackconfig}
-
-Import `loadRstackConfig` from `rstack/config` to load configurations programmatically:
-
-```ts
-import { loadRstackConfig } from 'rstack/config';
-
-const { configs, filePath, dependencies } = await loadRstackConfig({
-  cwd: process.cwd(),
-  configFilePath: './rstack.config.ts',
-});
-```
-
-Both options are optional:
-
-- `cwd`: the directory used to search for a configuration file and resolve relative configuration file paths. Defaults to the current working directory.
-- `configFilePath`: a relative or absolute configuration file path. If omitted, uses the CLI's `--config` path when set; otherwise, searches for the [default configuration file names](./configuration#configuration-file) in `cwd`.
-
-The returned object contains:
-
-- `configs`: tool configuration definitions that include both shared and project settings. Tools with no configuration are omitted.
-- `filePath`: the loaded configuration file's path, or `null` if no file was found.
-- `dependencies`: the configuration's dependencies, as reported by the loader.
-
-The loader leaves configuration functions unevaluated. It may also return an async function for a tool whose inputs were all objects, so those objects can be merged when the tool is needed.
-
-When using the result, resolve each definition with the parameters its tool expects, then follow that tool's setup and execution steps. Rstack's automatic test inheritance and formatting normalization still need to run at that stage. A `staged` function is a task generator: call it with the staged file names when running tasks.
-
-`rstack/config` also exports the `Configs`, `LoadedRstackConfig`, and `LoadRstackConfigOptions` types.
-
 ## Re-exports
 
 The tool-specific subpaths below re-export the public APIs from their corresponding core packages. Using these entry points keeps imports unified and APIs aligned with the tool versions integrated by Rstack CLI.
diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx
index 6ccd0761..00d2d8d0 100644
--- a/website/docs/zh/guide/api-reference.mdx
+++ b/website/docs/zh/guide/api-reference.mdx
@@ -11,7 +11,6 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
 | 导入路径                 | 内容                                      | 使用场景                 |
 | ------------------------ | ----------------------------------------- | ------------------------ |
 | `rstack`                 | Rstack CLI 配置 API                       | 注册各项工具配置         |
-| `rstack/config`          | 配置加载器及其类型                        | 加载公共配置和项目配置   |
 | `rstack/app`             | `@rsbuild/core` 的公开 API                | 构建应用及扩展 Rsbuild   |
 | `rstack/lib`             | `@rslib/core` 的公开 API                  | 构建库及扩展 Rslib       |
 | `rstack/test`            | `@rstest/core` 的公开 API                 | 编写测试及配置测试项目   |
@@ -28,21 +27,11 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
 
 ### `define.extends()` \{#define-extends}
 
-继承公共配置，再应用项目自己的配置：
+继承公共配置。
 
-```ts
-import { define } from 'rstack';
-import { sharedConfig } from './shared.ts';
-
-define.extends([sharedConfig]);
-```
+**类型：** `(configs: readonly RstackConfig[]) => void`
 
-- **类型：** `(configs: readonly RstackConfig[]) => void`
-- 传入配置对象数组。如果预设是函数，请先调用它，再传入返回的对象。
-- 每次加载配置时最多调用一次，传入空数组也算一次调用。
-- 先从左到右应用公共配置，再应用项目的 `define.*()` 配置，与调用顺序无关。
-
-嵌套继承、合并规则和示例请参阅[公共配置](./configuration#shared-configurations)。
+用法和合并规则请参阅[公共配置](./configuration#shared-configurations)。
 
 ### `RstackConfig`
 
@@ -58,38 +47,6 @@ export const sharedConfig: RstackConfig = {
 };
 ```
 
-## 加载配置 \{#loading-configurations}
-
-### `loadRstackConfig()` \{#loadrstackconfig}
-
-从 `rstack/config` 导入 `loadRstackConfig`，以编程方式加载配置：
-
-```ts
-import { loadRstackConfig } from 'rstack/config';
-
-const { configs, filePath, dependencies } = await loadRstackConfig({
-  cwd: process.cwd(),
-  configFilePath: './rstack.config.ts',
-});
-```
-
-两个选项均可省略：
-
-- `cwd`：用于查找配置文件和解析相对配置文件路径的目录，默认为当前工作目录。
-- `configFilePath`：配置文件的相对或绝对路径。省略时，优先使用 CLI 的 `--config` 路径；如果未设置，则在 `cwd` 中查找[默认配置文件名](./configuration#configuration-file)。
-
-返回对象包含：
-
-- `configs`：包含公共配置和项目配置的工具配置定义。未配置的工具不会出现在该对象中。
-- `filePath`：加载的配置文件路径，未找到文件时为 `null`。
-- `dependencies`：加载器报告的配置依赖。
-
-加载器不会执行配置函数。即使某个工具的配置全部以对象形式传入，返回的字段也可能是异步函数，以便在需要该工具时再合并这些对象。
-
-使用返回结果时，需要按各工具的要求传入参数、解析配置，再执行相应的初始化和运行流程。Rstack 的测试自动继承和格式化配置标准化也需要在这个阶段完成。`staged` 函数用于生成任务，应在运行任务时传入暂存文件名。
-
-`rstack/config` 还导出 `Configs`、`LoadedRstackConfig` 和 `LoadRstackConfigOptions` 类型。
-
 ## 重导出 \{#re-exports}
 
 以下工具子路径均会重导出对应 core 包的公开 API。通过这些入口导入，可以统一依赖入口，并确保 API 与 Rstack CLI 集成的工具版本匹配。

From 3c996707dedba53d38fbf5833e36ddc38d1ef01f Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 9 Oct 2026 17:03:16 +0800
Subject: [PATCH 3/9] docs: clarify extends API description

---
 website/docs/en/guide/api-reference.mdx | 2 +-
 website/docs/zh/guide/api-reference.mdx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx
index 61c01c9c..058a683b 100644
--- a/website/docs/en/guide/api-reference.mdx
+++ b/website/docs/en/guide/api-reference.mdx
@@ -27,7 +27,7 @@ Import `define` from `rstack` to register tool configurations in `rstack.config.
 
 ### `define.extends()` \{#define-extends}
 
-Inherits shared configurations.
+Accepts an array of shared configuration objects and applies their tool settings before merging the project's own `define.*()` configurations.
 
 **Type:** `(configs: readonly RstackConfig[]) => void`
 
diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx
index 00d2d8d0..2fd202ce 100644
--- a/website/docs/zh/guide/api-reference.mdx
+++ b/website/docs/zh/guide/api-reference.mdx
@@ -27,7 +27,7 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
 
 ### `define.extends()` \{#define-extends}
 
-继承公共配置。
+接收一组公共配置对象，先应用其中各工具的配置，再合并当前项目通过 `define.*()` 定义的配置。
 
 **类型：** `(configs: readonly RstackConfig[]) => void`
 

From 32a51ef9b83fdc3e99a6687cef9b747266cfd310 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 9 Oct 2026 17:04:33 +0800
Subject: [PATCH 4/9] docs: group extends with configuration APIs

---
 website/docs/en/guide/api-reference.mdx |  8 --------
 website/docs/en/guide/configuration.mdx | 27 ++++++++++++++++---------
 website/docs/zh/guide/api-reference.mdx |  8 --------
 website/docs/zh/guide/configuration.mdx | 27 ++++++++++++++++---------
 4 files changed, 36 insertions(+), 34 deletions(-)

diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx
index 058a683b..aad17eb1 100644
--- a/website/docs/en/guide/api-reference.mdx
+++ b/website/docs/en/guide/api-reference.mdx
@@ -25,14 +25,6 @@ Rstack CLI provides a unified configuration API and re-exports the public APIs o
 
 Import `define` from `rstack` to register tool configurations in `rstack.config.ts`; see [Configuration APIs](./configuration#configuration-apis) for details.
 
-### `define.extends()` \{#define-extends}
-
-Accepts an array of shared configuration objects and applies their tool settings before merging the project's own `define.*()` configurations.
-
-**Type:** `(configs: readonly RstackConfig[]) => void`
-
-See [Shared configurations](./configuration#shared-configurations) for usage and merge rules.
-
 ### `RstackConfig`
 
 Use this type to define a shared configuration. All fields are optional: `app`, `lib`, `doc`, `test`, `lint`, `fmt`, and `staged` accept the same values as their corresponding `define.*()` APIs. Add `extends`, typed as `readonly RstackConfig[]`, to inherit other shared configurations.
diff --git a/website/docs/en/guide/configuration.mdx b/website/docs/en/guide/configuration.mdx
index 29183e66..bccf0c51 100644
--- a/website/docs/en/guide/configuration.mdx
+++ b/website/docs/en/guide/configuration.mdx
@@ -78,15 +78,24 @@ define.fmt({
 
 Configuration options follow the formats of the underlying tools. When using APIs and helpers that Rstack CLI re-exports, prefer the `rstack/app`, `rstack/lib`, `rstack/test`, and `rstack/lint` entry points.
 
-| API                                 | Tool                                                                    | Commands                                                                        |
-| ----------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| [`define.app()`](#define-app)       | [Rsbuild](https://rsbuild.rs/config/)                                   | [`rs dev`](./cli/dev), [`rs build`](./cli/build), [`rs preview`](./cli/preview) |
-| [`define.lib()`](#define-lib)       | [Rslib](https://rslib.rs/config/)                                       | [`rs lib`](./cli/lib)                                                           |
-| [`define.doc()`](#define-doc)       | [Rspress](https://rspress.rs/api/config/config-basic)                   | [`rs doc`](./cli/doc)                                                           |
-| [`define.test()`](#define-test)     | [Rstest](https://rstest.rs/config/)                                     | [`rs test`](./cli/test)                                                         |
-| [`define.lint()`](#define-lint)     | [Rslint](https://rslint.rs/config/)                                     | [`rs lint`](./cli/lint)                                                         |
-| [`define.fmt()`](#define-fmt)       | [Prettier](https://prettier.io/docs/options)                            | [`rs fmt`](./cli/fmt)                                                           |
-| [`define.staged()`](#define-staged) | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged)                                                     |
+| API                                   | Tool                                                                    | Commands                                                                        |
+| ------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| [`define.extends()`](#define-extends) | —                                                                       | —                                                                               |
+| [`define.app()`](#define-app)         | [Rsbuild](https://rsbuild.rs/config/)                                   | [`rs dev`](./cli/dev), [`rs build`](./cli/build), [`rs preview`](./cli/preview) |
+| [`define.lib()`](#define-lib)         | [Rslib](https://rslib.rs/config/)                                       | [`rs lib`](./cli/lib)                                                           |
+| [`define.doc()`](#define-doc)         | [Rspress](https://rspress.rs/api/config/config-basic)                   | [`rs doc`](./cli/doc)                                                           |
+| [`define.test()`](#define-test)       | [Rstest](https://rstest.rs/config/)                                     | [`rs test`](./cli/test)                                                         |
+| [`define.lint()`](#define-lint)       | [Rslint](https://rslint.rs/config/)                                     | [`rs lint`](./cli/lint)                                                         |
+| [`define.fmt()`](#define-fmt)         | [Prettier](https://prettier.io/docs/options)                            | [`rs fmt`](./cli/fmt)                                                           |
+| [`define.staged()`](#define-staged)   | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged)                                                     |
+
+### `define.extends()` \{#define-extends}
+
+Accepts an array of shared configuration objects and applies their tool settings before merging the project's own `define.*()` configurations.
+
+**Type:** `(configs: readonly RstackConfig[]) => void`
+
+See [Shared configurations](#shared-configurations) for usage and merge rules.
 
 ### `define.app()` \{#define-app}
 
diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx
index 2fd202ce..eee09975 100644
--- a/website/docs/zh/guide/api-reference.mdx
+++ b/website/docs/zh/guide/api-reference.mdx
@@ -25,14 +25,6 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
 
 从 `rstack` 导入 `define`，用于在 `rstack.config.ts` 中注册各项工具配置；详细用法请参阅[配置 API](./configuration#configuration-apis)。
 
-### `define.extends()` \{#define-extends}
-
-接收一组公共配置对象，先应用其中各工具的配置，再合并当前项目通过 `define.*()` 定义的配置。
-
-**类型：** `(configs: readonly RstackConfig[]) => void`
-
-用法和合并规则请参阅[公共配置](./configuration#shared-configurations)。
-
 ### `RstackConfig`
 
 使用这个类型定义公共配置。所有字段均为可选：`app`、`lib`、`doc`、`test`、`lint`、`fmt` 和 `staged` 的用法与对应的 `define.*()` API 一致。需要继承其他公共配置时，可以添加类型为 `readonly RstackConfig[]` 的 `extends` 字段。
diff --git a/website/docs/zh/guide/configuration.mdx b/website/docs/zh/guide/configuration.mdx
index b0f3e9d0..1f588c75 100644
--- a/website/docs/zh/guide/configuration.mdx
+++ b/website/docs/zh/guide/configuration.mdx
@@ -78,15 +78,24 @@ define.fmt({
 
 各 API 沿用底层工具的配置格式。使用 Rstack CLI 已重导出的 API 和辅助函数时，推荐从 `rstack/app`、`rstack/lib`、`rstack/test` 和 `rstack/lint` 入口导入。
 
-| API                                 | 底层工具                                                                | 对应命令                                                                        |
-| ----------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| [`define.app()`](#define-app)       | [Rsbuild](https://rsbuild.rs/zh/config/)                                | [`rs dev`](./cli/dev)、[`rs build`](./cli/build)、[`rs preview`](./cli/preview) |
-| [`define.lib()`](#define-lib)       | [Rslib](https://rslib.rs/zh/config/)                                    | [`rs lib`](./cli/lib)                                                           |
-| [`define.doc()`](#define-doc)       | [Rspress](https://rspress.rs/zh/api/config/config-basic)                | [`rs doc`](./cli/doc)                                                           |
-| [`define.test()`](#define-test)     | [Rstest](https://rstest.rs/zh/config/)                                  | [`rs test`](./cli/test)                                                         |
-| [`define.lint()`](#define-lint)     | [Rslint](https://rslint.rs/config/)                                     | [`rs lint`](./cli/lint)                                                         |
-| [`define.fmt()`](#define-fmt)       | [Prettier](https://prettier.io/docs/options)                            | [`rs fmt`](./cli/fmt)                                                           |
-| [`define.staged()`](#define-staged) | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged)                                                     |
+| API                                   | 底层工具                                                                | 对应命令                                                                        |
+| ------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| [`define.extends()`](#define-extends) | —                                                                       | —                                                                               |
+| [`define.app()`](#define-app)         | [Rsbuild](https://rsbuild.rs/zh/config/)                                | [`rs dev`](./cli/dev)、[`rs build`](./cli/build)、[`rs preview`](./cli/preview) |
+| [`define.lib()`](#define-lib)         | [Rslib](https://rslib.rs/zh/config/)                                    | [`rs lib`](./cli/lib)                                                           |
+| [`define.doc()`](#define-doc)         | [Rspress](https://rspress.rs/zh/api/config/config-basic)                | [`rs doc`](./cli/doc)                                                           |
+| [`define.test()`](#define-test)       | [Rstest](https://rstest.rs/zh/config/)                                  | [`rs test`](./cli/test)                                                         |
+| [`define.lint()`](#define-lint)       | [Rslint](https://rslint.rs/config/)                                     | [`rs lint`](./cli/lint)                                                         |
+| [`define.fmt()`](#define-fmt)         | [Prettier](https://prettier.io/docs/options)                            | [`rs fmt`](./cli/fmt)                                                           |
+| [`define.staged()`](#define-staged)   | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged)                                                     |
+
+### `define.extends()` \{#define-extends}
+
+接收一组公共配置对象，先应用其中各工具的配置，再合并当前项目通过 `define.*()` 定义的配置。
+
+**类型：** `(configs: readonly RstackConfig[]) => void`
+
+用法和合并规则请参阅[公共配置](#shared-configurations)。
 
 ### `define.app()` \{#define-app}
 

From 3cd57d03d515d9763a56244047599a3b98144602 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 9 Oct 2026 17:05:02 +0800
Subject: [PATCH 5/9] docs: link shared configuration type to guide

---
 website/docs/en/guide/api-reference.mdx | 2 +-
 website/docs/zh/guide/api-reference.mdx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx
index aad17eb1..870d46f3 100644
--- a/website/docs/en/guide/api-reference.mdx
+++ b/website/docs/en/guide/api-reference.mdx
@@ -27,7 +27,7 @@ Import `define` from `rstack` to register tool configurations in `rstack.config.
 
 ### `RstackConfig`
 
-Use this type to define a shared configuration. All fields are optional: `app`, `lib`, `doc`, `test`, `lint`, `fmt`, and `staged` accept the same values as their corresponding `define.*()` APIs. Add `extends`, typed as `readonly RstackConfig[]`, to inherit other shared configurations.
+Use this type to define a [shared configuration](./configuration#shared-configurations). All fields are optional: `app`, `lib`, `doc`, `test`, `lint`, `fmt`, and `staged` accept the same values as their corresponding `define.*()` APIs. Add `extends`, typed as `readonly RstackConfig[]`, to inherit other shared configurations.
 
 ```ts
 import type { RstackConfig } from 'rstack';
diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx
index eee09975..7d10814f 100644
--- a/website/docs/zh/guide/api-reference.mdx
+++ b/website/docs/zh/guide/api-reference.mdx
@@ -27,7 +27,7 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
 
 ### `RstackConfig`
 
-使用这个类型定义公共配置。所有字段均为可选：`app`、`lib`、`doc`、`test`、`lint`、`fmt` 和 `staged` 的用法与对应的 `define.*()` API 一致。需要继承其他公共配置时，可以添加类型为 `readonly RstackConfig[]` 的 `extends` 字段。
+使用这个类型定义[公共配置](./configuration#shared-configurations)。所有字段均为可选：`app`、`lib`、`doc`、`test`、`lint`、`fmt` 和 `staged` 的用法与对应的 `define.*()` API 一致。需要继承其他公共配置时，可以添加类型为 `readonly RstackConfig[]` 的 `extends` 字段。
 
 ```ts
 import type { RstackConfig } from 'rstack';

From 866e6a2e8ea0b08b6e223ce559700c36d32a20c7 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 9 Oct 2026 17:06:49 +0800
Subject: [PATCH 6/9] docs: place extends after staged configuration

---
 website/docs/en/guide/configuration.mdx | 18 +++++++++---------
 website/docs/zh/guide/configuration.mdx | 18 +++++++++---------
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/website/docs/en/guide/configuration.mdx b/website/docs/en/guide/configuration.mdx
index bccf0c51..68844127 100644
--- a/website/docs/en/guide/configuration.mdx
+++ b/website/docs/en/guide/configuration.mdx
@@ -80,7 +80,6 @@ Configuration options follow the formats of the underlying tools. When using API
 
 | API                                   | Tool                                                                    | Commands                                                                        |
 | ------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| [`define.extends()`](#define-extends) | —                                                                       | —                                                                               |
 | [`define.app()`](#define-app)         | [Rsbuild](https://rsbuild.rs/config/)                                   | [`rs dev`](./cli/dev), [`rs build`](./cli/build), [`rs preview`](./cli/preview) |
 | [`define.lib()`](#define-lib)         | [Rslib](https://rslib.rs/config/)                                       | [`rs lib`](./cli/lib)                                                           |
 | [`define.doc()`](#define-doc)         | [Rspress](https://rspress.rs/api/config/config-basic)                   | [`rs doc`](./cli/doc)                                                           |
@@ -88,14 +87,7 @@ Configuration options follow the formats of the underlying tools. When using API
 | [`define.lint()`](#define-lint)       | [Rslint](https://rslint.rs/config/)                                     | [`rs lint`](./cli/lint)                                                         |
 | [`define.fmt()`](#define-fmt)         | [Prettier](https://prettier.io/docs/options)                            | [`rs fmt`](./cli/fmt)                                                           |
 | [`define.staged()`](#define-staged)   | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged)                                                     |
-
-### `define.extends()` \{#define-extends}
-
-Accepts an array of shared configuration objects and applies their tool settings before merging the project's own `define.*()` configurations.
-
-**Type:** `(configs: readonly RstackConfig[]) => void`
-
-See [Shared configurations](#shared-configurations) for usage and merge rules.
+| [`define.extends()`](#define-extends) | —                                                                       | —                                                                               |
 
 ### `define.app()` \{#define-app}
 
@@ -214,6 +206,14 @@ define.staged({
 
 Provide a staged configuration through `define.staged()` or a [shared configuration](#shared-configurations). `rs staged` reports an error if neither provides one.
 
+### `define.extends()` \{#define-extends}
+
+Accepts an array of shared configuration objects and applies their tool settings before merging the project's own `define.*()` configurations.
+
+**Type:** `(configs: readonly RstackConfig[]) => void`
+
+See [Shared configurations](#shared-configurations) for usage and merge rules.
+
 ## Shared configurations
 
 Use `define.extends()` to share build, test, lint, and formatting settings across projects. A shared configuration is a plain object whose fields accept the same values as the corresponding `define.*()` APIs. In TypeScript, use `RstackConfig` to check its types:
diff --git a/website/docs/zh/guide/configuration.mdx b/website/docs/zh/guide/configuration.mdx
index 1f588c75..ddcbfb7c 100644
--- a/website/docs/zh/guide/configuration.mdx
+++ b/website/docs/zh/guide/configuration.mdx
@@ -80,7 +80,6 @@ define.fmt({
 
 | API                                   | 底层工具                                                                | 对应命令                                                                        |
 | ------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| [`define.extends()`](#define-extends) | —                                                                       | —                                                                               |
 | [`define.app()`](#define-app)         | [Rsbuild](https://rsbuild.rs/zh/config/)                                | [`rs dev`](./cli/dev)、[`rs build`](./cli/build)、[`rs preview`](./cli/preview) |
 | [`define.lib()`](#define-lib)         | [Rslib](https://rslib.rs/zh/config/)                                    | [`rs lib`](./cli/lib)                                                           |
 | [`define.doc()`](#define-doc)         | [Rspress](https://rspress.rs/zh/api/config/config-basic)                | [`rs doc`](./cli/doc)                                                           |
@@ -88,14 +87,7 @@ define.fmt({
 | [`define.lint()`](#define-lint)       | [Rslint](https://rslint.rs/config/)                                     | [`rs lint`](./cli/lint)                                                         |
 | [`define.fmt()`](#define-fmt)         | [Prettier](https://prettier.io/docs/options)                            | [`rs fmt`](./cli/fmt)                                                           |
 | [`define.staged()`](#define-staged)   | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged)                                                     |
-
-### `define.extends()` \{#define-extends}
-
-接收一组公共配置对象，先应用其中各工具的配置，再合并当前项目通过 `define.*()` 定义的配置。
-
-**类型：** `(configs: readonly RstackConfig[]) => void`
-
-用法和合并规则请参阅[公共配置](#shared-configurations)。
+| [`define.extends()`](#define-extends) | —                                                                       | —                                                                               |
 
 ### `define.app()` \{#define-app}
 
@@ -214,6 +206,14 @@ define.staged({
 
 请通过 `define.staged()` 或[公共配置](#shared-configurations)提供 staged 配置，否则 `rs staged` 会报错。
 
+### `define.extends()` \{#define-extends}
+
+接收一组公共配置对象，先应用其中各工具的配置，再合并当前项目通过 `define.*()` 定义的配置。
+
+**类型：** `(configs: readonly RstackConfig[]) => void`
+
+用法和合并规则请参阅[公共配置](#shared-configurations)。
+
 ## 公共配置 \{#shared-configurations}
 
 使用 `define.extends()` 可以在多个项目之间共享构建、测试、lint 和格式化配置。公共配置是一个普通对象，各字段的用法与对应的 `define.*()` API 一致。在 TypeScript 中，可以用 `RstackConfig` 检查配置类型：

From e8ee9f6829fe34c57aee777e93b1f979b28bed3d Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 9 Oct 2026 17:08:28 +0800
Subject: [PATCH 7/9] docs: clarify shared configuration type fields

---
 website/docs/en/guide/api-reference.mdx | 6 +++++-
 website/docs/zh/guide/api-reference.mdx | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx
index 870d46f3..f29bba7c 100644
--- a/website/docs/en/guide/api-reference.mdx
+++ b/website/docs/en/guide/api-reference.mdx
@@ -27,7 +27,11 @@ Import `define` from `rstack` to register tool configurations in `rstack.config.
 
 ### `RstackConfig`
 
-Use this type to define a [shared configuration](./configuration#shared-configurations). All fields are optional: `app`, `lib`, `doc`, `test`, `lint`, `fmt`, and `staged` accept the same values as their corresponding `define.*()` APIs. Add `extends`, typed as `readonly RstackConfig[]`, to inherit other shared configurations.
+`RstackConfig` is the type for a [shared configuration](./configuration#shared-configurations). All fields are optional, so include only the settings you want to share.
+
+Each tool field accepts the same configuration as its corresponding `define.*()` method. For example, `fmt` accepts the same input as `define.fmt()`.
+
+Use the `extends` field to inherit other shared configurations. Its type is `readonly RstackConfig[]`.
 
 ```ts
 import type { RstackConfig } from 'rstack';
diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx
index 7d10814f..e6172869 100644
--- a/website/docs/zh/guide/api-reference.mdx
+++ b/website/docs/zh/guide/api-reference.mdx
@@ -27,7 +27,11 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
 
 ### `RstackConfig`
 
-使用这个类型定义[公共配置](./configuration#shared-configurations)。所有字段均为可选：`app`、`lib`、`doc`、`test`、`lint`、`fmt` 和 `staged` 的用法与对应的 `define.*()` API 一致。需要继承其他公共配置时，可以添加类型为 `readonly RstackConfig[]` 的 `extends` 字段。
+`RstackConfig` 是[公共配置](./configuration#shared-configurations)的类型。所有字段均为可选，只需填写需要共享的配置。
+
+各工具字段接受与对应 `define.*()` 方法相同的配置，例如 `fmt` 对应 `define.fmt()`。
+
+还可以通过 `extends` 字段继承其他公共配置，该字段的类型为 `readonly RstackConfig[]`。
 
 ```ts
 import type { RstackConfig } from 'rstack';

From c86ca217f9e6954bc26e8347693a351773065cc0 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 9 Oct 2026 17:09:57 +0800
Subject: [PATCH 8/9] docs: add nested shared configuration example

---
 website/docs/en/guide/api-reference.mdx | 18 +++++++++++++++---
 website/docs/zh/guide/api-reference.mdx | 18 +++++++++++++++---
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx
index f29bba7c..d8d7045e 100644
--- a/website/docs/en/guide/api-reference.mdx
+++ b/website/docs/en/guide/api-reference.mdx
@@ -31,9 +31,7 @@ Import `define` from `rstack` to register tool configurations in `rstack.config.
 
 Each tool field accepts the same configuration as its corresponding `define.*()` method. For example, `fmt` accepts the same input as `define.fmt()`.
 
-Use the `extends` field to inherit other shared configurations. Its type is `readonly RstackConfig[]`.
-
-```ts
+```ts title="shared.ts"
 import type { RstackConfig } from 'rstack';
 
 export const sharedConfig: RstackConfig = {
@@ -43,6 +41,20 @@ export const sharedConfig: RstackConfig = {
 };
 ```
 
+Use the `extends` field to inherit other shared configurations. Its type is `readonly RstackConfig[]`.
+
+```ts title="team.ts"
+import type { RstackConfig } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+export const teamConfig: RstackConfig = {
+  extends: [sharedConfig],
+  fmt: {
+    printWidth: 100,
+  },
+};
+```
+
 ## Re-exports
 
 The tool-specific subpaths below re-export the public APIs from their corresponding core packages. Using these entry points keeps imports unified and APIs aligned with the tool versions integrated by Rstack CLI.
diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx
index e6172869..75ec80f5 100644
--- a/website/docs/zh/guide/api-reference.mdx
+++ b/website/docs/zh/guide/api-reference.mdx
@@ -31,9 +31,7 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
 
 各工具字段接受与对应 `define.*()` 方法相同的配置，例如 `fmt` 对应 `define.fmt()`。
 
-还可以通过 `extends` 字段继承其他公共配置，该字段的类型为 `readonly RstackConfig[]`。
-
-```ts
+```ts title="shared.ts"
 import type { RstackConfig } from 'rstack';
 
 export const sharedConfig: RstackConfig = {
@@ -43,6 +41,20 @@ export const sharedConfig: RstackConfig = {
 };
 ```
 
+还可以通过 `extends` 字段继承其他公共配置，该字段的类型为 `readonly RstackConfig[]`。
+
+```ts title="team.ts"
+import type { RstackConfig } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+export const teamConfig: RstackConfig = {
+  extends: [sharedConfig],
+  fmt: {
+    printWidth: 100,
+  },
+};
+```
+
 ## 重导出 \{#re-exports}
 
 以下工具子路径均会重导出对应 core 包的公开 API。通过这些入口导入，可以统一依赖入口，并确保 API 与 Rstack CLI 集成的工具版本匹配。

From ad9b51077aeca383e9006f020ed92169c76c1740 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Fri, 9 Oct 2026 17:12:15 +0800
Subject: [PATCH 9/9] docs: fold shared test configuration notes into
 inheritance

---
 website/docs/en/guide/testing.mdx | 44 ++-----------------------------
 website/docs/zh/guide/testing.mdx | 44 ++-----------------------------
 2 files changed, 4 insertions(+), 84 deletions(-)

diff --git a/website/docs/en/guide/testing.mdx b/website/docs/en/guide/testing.mdx
index fdeeec94..c5a11fa9 100644
--- a/website/docs/en/guide/testing.mdx
+++ b/website/docs/en/guide/testing.mdx
@@ -36,6 +36,8 @@ import { defineInlineProject, expect, test } from 'rstack/test';
 
 When `define.test()` does not set Rstest's [`extends`](https://rstest.rs/config/test/extends), Rstack CLI automatically converts the configuration registered by `define.app()` or `define.lib()` into an Rstest configuration. The inherited configuration is merged with the options passed directly to `define.test()`.
 
+When using [shared configurations](./configuration#shared-configurations), Rstack first merges the shared and project test settings, then determines whether automatic inheritance is needed. If it is, Rstack uses the merged App or Lib configuration.
+
 ### Inherit the application configuration
 
 When `define.app()` is registered, Rstack CLI converts it with [`@rstest/adapter-rsbuild`](https://rstest.rs/guide/integration/rsbuild) and uses the result as the test configuration's `extends` value:
@@ -107,48 +109,6 @@ define.test({
 
 For multiple projects, setting `extends` on the root `define.test()` configuration disables automatic inheritance for every project. Setting it on an inline project disables inheritance only for that project.
 
-### Shared test configurations
-
-A [shared configuration](./configuration#shared-configurations) can provide both build and test settings. Rstack combines these with the project's settings before deciding whether tests should inherit the build configuration.
-
-First, Rstack merges the test settings with `mergeRstestConfig`. It then checks `extends` and `projects` in the merged result. Tests that need automatic inheritance use the merged App configuration, or the merged Lib configuration if no App configuration is defined.
-
-`define.extends()` and Rstest's `test.extends` serve different purposes: the former shares settings across tools; the latter controls Rstest's own configuration inheritance.
-
-```ts title="shared.ts"
-import type { RstackConfig } from 'rstack';
-
-export const sharedConfig: RstackConfig = {
-  app: {
-    resolve: {
-      alias: {
-        '@': './src',
-      },
-    },
-  },
-  test: {
-    retry: 2,
-  },
-};
-```
-
-```ts title="rstack.config.ts"
-import { define } from 'rstack';
-import { sharedConfig } from './shared.ts';
-
-define.extends([sharedConfig]);
-
-define.test({
-  testEnvironment: 'happy-dom',
-});
-```
-
-Tests run in happy-dom with `retry: 2` and inherit the shared App configuration's `@` alias. There is no need to call `define.app()` in the project.
-
-To disable automatic inheritance, set `extends` explicitly in the test configuration. This also works in a shared configuration: if the merged test settings contain `extends`, even as `extends: undefined`, automatic inheritance is disabled.
-
-For multiple projects, Rstack checks the merged inline projects individually. External projects specified by strings still load their own configurations. If no project needs automatic inheritance, Rstack skips the App and Lib configuration functions.
-
 ## Multiple projects
 
 Set Rstest's [`projects`](https://rstest.rs/config/test/projects) option to run multiple test configurations together. Entries can be inline projects or strings that Rstest resolves as external projects.
diff --git a/website/docs/zh/guide/testing.mdx b/website/docs/zh/guide/testing.mdx
index 961cdf51..9aa005f6 100644
--- a/website/docs/zh/guide/testing.mdx
+++ b/website/docs/zh/guide/testing.mdx
@@ -36,6 +36,8 @@ import { defineInlineProject, expect, test } from 'rstack/test';
 
 当 `define.test()` 未设置 Rstest 的 [`extends`](https://rstest.rs/zh/config/test/extends) 时，Rstack CLI 会自动将 `define.app()` 或 `define.lib()` 注册的配置转换为 Rstest 配置，再与直接传给 `define.test()` 的选项合并。
 
+使用[公共配置](./configuration#shared-configurations)时，Rstack 会先合并公共配置和项目中的测试配置，再判断是否需要自动继承。需要继承时，使用合并后的 App 或 Lib 配置。
+
 ### 继承应用配置 \{#inherit-the-application-configuration}
 
 注册 `define.app()` 后，Rstack CLI 会通过 [`@rstest/adapter-rsbuild`](https://rstest.rs/zh/guide/integration/rsbuild) 转换该配置，并将结果作为测试配置的 `extends`：
@@ -107,48 +109,6 @@ define.test({
 
 使用多项目配置时，在 `define.test()` 根配置中设置 `extends` 会关闭所有项目的自动继承；在某个内联项目中设置 `extends` 则只会关闭该项目的自动继承。
 
-### 公共测试配置 \{#shared-test-configurations}
-
-[公共配置](./configuration#shared-configurations) 可以同时提供构建和测试配置。Rstack 会先将它们与项目配置合并，再判断测试是否需要继承构建配置。
-
-Rstack 首先使用 `mergeRstestConfig` 合并测试配置，再检查合并结果中的 `extends` 和 `projects`。需要自动继承的测试会使用合并后的 App 配置；没有定义 App 配置时，则使用合并后的 Lib 配置。
-
-`define.extends()` 用于在多个工具之间共享配置，Rstest 的 `test.extends` 则控制测试配置自身的继承，两者用途不同。
-
-```ts title="shared.ts"
-import type { RstackConfig } from 'rstack';
-
-export const sharedConfig: RstackConfig = {
-  app: {
-    resolve: {
-      alias: {
-        '@': './src',
-      },
-    },
-  },
-  test: {
-    retry: 2,
-  },
-};
-```
-
-```ts title="rstack.config.ts"
-import { define } from 'rstack';
-import { sharedConfig } from './shared.ts';
-
-define.extends([sharedConfig]);
-
-define.test({
-  testEnvironment: 'happy-dom',
-});
-```
-
-测试会在 happy-dom 中运行，使用 `retry: 2`，并继承公共 App 配置中的 `@` 别名。项目中无需再调用 `define.app()`。
-
-如果要关闭自动继承，请在测试配置中显式设置 `extends`。在公共配置中设置也同样有效：只要合并后的测试配置包含 `extends`，即使值为 `undefined`，自动继承也会关闭。
-
-使用多项目配置时，Rstack 会逐一检查合并后的内联项目。字符串形式的外部项目仍独立加载自己的配置。如果所有项目都不需要自动继承，Rstack 就会跳过 App 和 Lib 配置函数。
-
 ## 多项目 \{#multiple-projects}
 
 通过 Rstest 的 [`projects`](https://rstest.rs/zh/config/test/projects) 选项可以同时运行多套测试配置。每一项既可以是内联项目，也可以是由 Rstest 解析为外部项目的字符串。