diff --git a/‎website/docs/en/guide/api-reference.mdx‎
Lines changed: 63 additions & 0 deletions b/‎website/docs/en/guide/api-reference.mdx‎
Lines changed: 63 additions & 0 deletions
diff --git a/‎website/docs/en/guide/configuration.mdx‎
Lines changed: 168 additions & 1 deletion b/‎website/docs/en/guide/configuration.mdx‎
Lines changed: 168 additions & 1 deletion
diff --git a/‎website/docs/en/guide/testing.mdx‎
Lines changed: 38 additions & 0 deletions b/‎website/docs/en/guide/testing.mdx‎
Lines changed: 38 additions & 0 deletions
diff --git a/‎website/docs/zh/guide/api-reference.mdx‎
Lines changed: 63 additions & 0 deletions b/‎website/docs/zh/guide/api-reference.mdx‎
Lines changed: 63 additions & 0 deletions
@@ -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,68 @@ 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}
+
+Registers shared configurations to apply before the project's own tool configurations:
+
+```ts
+import { define } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+define.extends([sharedConfig]);
+```
+
+- **Type:** `(configs: readonly RstackConfig[]) => void`
+- Accepts configuration objects. For a parameterized preset, call the preset function and pass its return value.
+- Can be called at most once per configuration load, including calls with an empty array.
+- Applies shared configurations from left to right, then project definitions, regardless of call order.
+
+See [Shared configurations](./configuration#shared-configurations) for nested inheritance, merge rules, and examples.
+
+### `RstackConfig`
+
+A type for authoring shared configurations. Its optional `app`, `lib`, `doc`, `test`, `lint`, `fmt`, and `staged` fields accept the same inputs as the corresponding `define.*()` APIs. Its optional `extends` field accepts `readonly RstackConfig[]` for nested inheritance.
+
+```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`: effective tool definitions, including shared configurations and project definitions. A tool's field is absent if it was never defined.
+- `filePath`: the loaded configuration file's path, or `null` if no file was found.
+- `dependencies`: configuration dependencies reported by the loader.
+
+Configuration functions remain unevaluated. A field may be an async function even when all its inputs were objects, because merging is deferred until that tool is needed. Consumers must resolve definitions with the appropriate tool parameters and follow the tool's configuration and execution flow; this API does not return fully resolved runtime configurations. In particular, loading alone does not apply Rstack's automatic test inheritance or formatting normalization. Staged functions remain task generators that receive file names.
+
+`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.
 
@@ -74,6 +74,171 @@ define.fmt({
 });
 ```
 
+## Shared configurations
+
+Use `define.extends()` to reuse configurations across projects. A shared configuration is a plain object typed as `RstackConfig`. It can contain `app`, `lib`, `doc`, `test`, `lint`, `fmt`, and `staged`, each accepting the same input as its corresponding `define.*()` API.
+
+```ts title="shared.ts"
+import type { RstackConfig } from 'rstack';
+
+export const sharedConfig: RstackConfig = {
+  test: {
+    retry: 2,
+  },
+  lint: ({ js, ts }) => [js.configs.recommended, ts.configs.recommended],
+  fmt: {
+    singleQuote: true,
+    printWidth: 80,
+  },
+};
+```
+
+Import the object from a local module or an npm package, then customize the settings your project needs:
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+define.extends([sharedConfig]);
+
+define.fmt({
+  printWidth: 100,
+});
+```
+
+This project inherits the test and lint configurations and formats with `singleQuote: true` and `printWidth: 100`. You do not need to call `define.test()` or `define.lint()` to enable inherited settings.
+
+Call `define.extends()` at most once per configuration load, with all shared configurations in one array. A second call throws, even if the first call used an empty array. Call it while loading `rstack.config.*`, just like the other `define.*()` APIs.
+
+### Merge order
+
+Configurations are applied in this order:
+
+1. Shared configurations in the `define.extends()` array, from left to right.
+2. Project configurations registered with `define.*()`, regardless of where those calls appear relative to `define.extends()`.
+
+Later configurations take precedence according to each tool's [merge rules](#merge-rules).
+
+Shared configurations can also extend other shared configurations:
+
+```ts title="team.ts"
+import type { RstackConfig } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+export const teamConfig: RstackConfig = {
+  extends: [sharedConfig],
+  test: {
+    retry: 3,
+  },
+};
+```
+
+Inherited configurations are applied before the object that extends them. Here, the order is `sharedConfig → teamConfig → project configuration`.
+
+Each occurrence of a shared configuration is applied. For example, if both `a` and `b` extend `base`, `define.extends([a, b])` applies `base → a → base → b → project configuration`. This can append arrays more than once; plugin deduplication follows the underlying tool's behavior. Circular inheritance throws an error that identifies the reference path.
+
+### Merge rules
+
+Rstack merges configurations separately for each tool:
+
+| Field    | Merge behavior                                                                                                                                                                        |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app`    | Uses Rsbuild's `mergeRsbuildConfig`.                                                                                                                                                  |
+| `lib`    | Uses Rslib's `mergeRslibConfig`.                                                                                                                                                      |
+| `test`   | Uses Rstest's `mergeRstestConfig`, then determines whether to inherit the merged App or Lib configuration. See [Test configuration inheritance](./testing#configuration-inheritance). |
+| `lint`   | Concatenates configuration arrays in order; Rslint applies their rules.                                                                                                               |
+| `fmt`    | Shallow merge: later values replace earlier values for the same option. Arrays and objects, including `overrides`, are replaced as a whole.                                           |
+| `doc`    | Uses Rspress's `mergeDocConfig`: recursively merges objects, appends arrays, and replaces ordinary functions with later functions.                                                    |
+| `staged` | Shallow merge by glob pattern: later tasks replace earlier tasks for the same pattern, including command arrays and task functions.                                                   |
+
+For `doc`, when both values are defined and either is an array, Rspress treats the other value as a one-item array before concatenating them. These rules also apply to `builderConfig`: Rstack does not additionally call `mergeRsbuildConfig`. For example, a later `builderConfig.tools.rspack` callback replaces an earlier callback, while callback arrays are concatenated.
+
+For `staged`, if either the accumulated configuration or the next configuration is a top-level task-generator function, the next configuration replaces the accumulated configuration entirely. Subsequent glob mappings merge from that replacement; they do not restore earlier tasks. Task functions run when lint-staged supplies the staged file list, not while merging configurations.
+
+### App and lib presets
+
+A developer infrastructure team can maintain two presets: one for App + Test + Lint + Format, and another for Lib + Test + Lint + Format. Both can extend the `sharedConfig` above.
+
+A preset can be a regular function when consumers need options. Call it to produce an object before passing it to `define.extends()`:
+
+```ts title="app-preset.ts"
+import type { RstackConfig } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+export function appPreset(options: { title: string }): RstackConfig {
+  return {
+    extends: [sharedConfig],
+    app: async () => {
+      const { pluginReact } = await import('@rsbuild/plugin-react');
+      return {
+        plugins: [pluginReact()],
+        html: {
+          title: options.title,
+        },
+      };
+    },
+    test: {
+      testEnvironment: 'happy-dom',
+    },
+  };
+}
+```
+
+```ts title="lib-preset.ts"
+import type { RstackConfig } from 'rstack';
+import { sharedConfig } from './shared.ts';
+
+export const libPreset: RstackConfig = {
+  extends: [sharedConfig],
+  lib: {
+    format: 'esm',
+    dts: true,
+  },
+  test: {
+    testEnvironment: 'node',
+  },
+};
+```
+
+After publishing these presets as `@biz/app-preset` and `@biz/lib-preset`, an application can use:
+
+```ts title="rstack.config.ts (application)"
+import { appPreset } from '@biz/app-preset';
+import { define } from 'rstack';
+
+define.extends([appPreset({ title: 'My App' })]);
+```
+
+A library can use:
+
+```ts title="rstack.config.ts (library)"
+import { libPreset } from '@biz/lib-preset';
+import { define } from 'rstack';
+
+define.extends([libPreset]);
+```
+
+Make the presets' dependencies available: for this example, the App preset needs `@rsbuild/plugin-react`, and application projects need `happy-dom` for their tests.
+
+### Loading dependencies and resolving paths
+
+Shared configurations follow the same [dependency loading guidance](#loading-dependencies-on-demand) as project configurations. Only the tool configuration functions needed by a command are evaluated. In the App preset above, `rs lint` and `rs fmt` do not load the React plugin; `rs test` may load it when inheriting the App configuration. The outer `appPreset()` function runs when the configuration file is loaded, so keep tool-specific imports inside the relevant configuration function.
+
+Relative paths follow each tool's existing rules. They are not automatically resolved relative to the shared configuration module. For a file shipped with a preset, use an absolute path derived from that module:
+
+```ts title="shared.ts"
+import { fileURLToPath } from 'node:url';
+import type { RstackConfig } from 'rstack';
+
+export const sharedConfig: RstackConfig = {
+  test: {
+    setupFiles: [fileURLToPath(new URL('./setup.ts', import.meta.url))],
+  },
+};
+```
+
+Include `setup.ts` in the published package at that location, or adjust the path to the built file. Existing local configuration dependency tracking also applies to shared modules: editing an imported local shared configuration reloads App, Lib, and Doc configurations in their development or watch modes.
+
 ## Configuration APIs
 
 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.
@@ -158,6 +323,8 @@ When `extends` is omitted, Rstack CLI automatically connects the test configurat
 
 If the root test configuration does not define `extends` and contains `projects`, Rstack CLI applies automatic inheritance to each inline project that omits its own `extends`. A function-based application or library configuration is resolved once and shared by those projects. String project entries are passed to Rstest unchanged; they load their external configurations independently and do not inherit the current application or library configuration.
 
+When using shared configurations, these rules apply after merging all test configurations and use the merged App or Lib configuration. See [Shared test configurations](./testing#shared-test-configurations).
+
 > For more guidance on testing, see [Testing](./testing).
 
 ### `define.lint()` \{#define-lint}
@@ -201,4 +368,4 @@ define.staged({
 });
 ```
 
-Unlike the other commands, `rs staged` requires a `define.staged()` configuration and reports an error when it is missing.
+`rs staged` requires a staged configuration, provided by `define.staged()` or a shared configuration, and reports an error when it is missing.
@@ -107,6 +107,44 @@ 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
+
+[`define.extends()`](./configuration#shared-configurations) shares configurations across tools. The `extends` field inside a test configuration is Rstest's own inheritance option. These operate at different levels.
+
+Rstack first merges all shared and project test configurations using `mergeRstestConfig`. It then checks the resulting `extends` and `projects` fields to decide whether automatic inheritance is needed. If it is, Rstack uses the merged App configuration, or the merged Lib configuration when no App configuration is defined.
+
+```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 use `retry: 2`, run in happy-dom, and inherit the `@` alias from the shared App configuration. A local `define.app()` call is not required.
+
+The same opt-out rules apply to shared configurations: an explicit `extends` in the merged test configuration, including `extends: undefined`, disables automatic inheritance. Inline projects are checked after merging; external string projects still load independently. If no project needs automatic inheritance, Rstack does not evaluate App or Lib configuration functions for it.
+
 ## 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.
 
@@ -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,68 @@ 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`
+- 接受配置对象。对于带参数的预设，先调用预设函数，再传入返回值。
+- 每次加载配置时最多调用一次，传入空数组的调用也计入此限制。
+- 先从左到右应用公共配置，再应用项目配置，与调用位置无关。
+
+嵌套继承、合并规则和示例请参阅[公共配置](./configuration#shared-configurations)。
+
+### `RstackConfig`
+
+用于编写公共配置的类型。可选字段 `app`、`lib`、`doc`、`test`、`lint`、`fmt` 和 `staged` 接受与对应 `define.*()` API 相同的输入。可选字段 `extends` 接受 `readonly RstackConfig[]`，用于嵌套继承。
+
+```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`：加载器报告的配置依赖。
+
+配置函数保持未执行状态。即使输入全部是对象，返回的字段仍可能是异步函数，因为合并会推迟到需要该工具时进行。调用方需要传入相应工具的参数来解析配置定义，并遵循工具自身的配置和执行流程；此 API 不会返回完全解析后的运行时配置。尤其是，仅加载配置不会应用 Rstack 的测试自动继承或格式化配置标准化。Staged 函数仍是接收文件名的任务生成函数。
+
+`rstack/config` 还导出 `Configs`、`LoadedRstackConfig` 和 `LoadRstackConfigOptions` 类型。
+
 ## 重导出 \{#re-exports}
 
 以下工具子路径均会重导出对应 core 包的公开 API。通过这些入口导入，可以统一依赖入口，并确保 API 与 Rstack CLI 集成的工具版本匹配。