Skip to content

Commit aea2b87

Browse files
chenjiahanchenjiahan
committed
docs: explain shared configuration APIs and test inheritance
1 parent d9d6710 commit aea2b87

4 files changed

Lines changed: 214 additions & 0 deletions

File tree

‎website/docs/en/guide/api-reference.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Rstack CLI provides a unified configuration API and re-exports the public APIs o
1111
| Import path | Contents | Use case |
1212
| ------------------------ | ------------------------------------------------- | --------------------------------------- |
1313
| `rstack` | Rstack CLI configuration API | Register tool configurations |
14+
| `rstack/config` | Configuration loader and its types | Load shared and project configurations |
1415
| `rstack/app` | Public APIs from `@rsbuild/core` | Build applications and extend Rsbuild |
1516
| `rstack/lib` | Public APIs from `@rslib/core` | Build libraries and extend Rslib |
1617
| `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
2526

2627
Import `define` from `rstack` to register tool configurations in `rstack.config.ts`; see [Configuration APIs](./configuration#configuration-apis) for details.
2728

29+
### `define.extends()` \{#define-extends}
30+
31+
Inherits shared configurations before applying the project's own settings:
32+
33+
```ts
34+
import { define } from 'rstack';
35+
import { sharedConfig } from './shared.ts';
36+
37+
define.extends([sharedConfig]);
38+
```
39+
40+
- **Type:** `(configs: readonly RstackConfig[]) => void`
41+
- Pass an array of configuration objects. If a preset is a function, call it first and pass the returned object.
42+
- Call at most once per configuration load. An empty array still counts as a call.
43+
- Shared configurations are applied from left to right, followed by the project's `define.*()` settings, regardless of call order.
44+
45+
See [Shared configurations](./configuration#shared-configurations) for nested inheritance, merge rules, and examples.
46+
47+
### `RstackConfig`
48+
49+
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.
50+
51+
```ts
52+
import type { RstackConfig } from 'rstack';
53+
54+
export const sharedConfig: RstackConfig = {
55+
fmt: {
56+
singleQuote: true,
57+
},
58+
};
59+
```
60+
61+
## Loading configurations
62+
63+
### `loadRstackConfig()` \{#loadrstackconfig}
64+
65+
Import `loadRstackConfig` from `rstack/config` to load configurations programmatically:
66+
67+
```ts
68+
import { loadRstackConfig } from 'rstack/config';
69+
70+
const { configs, filePath, dependencies } = await loadRstackConfig({
71+
cwd: process.cwd(),
72+
configFilePath: './rstack.config.ts',
73+
});
74+
```
75+
76+
Both options are optional:
77+
78+
- `cwd`: the directory used to search for a configuration file and resolve relative configuration file paths. Defaults to the current working directory.
79+
- `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`.
80+
81+
The returned object contains:
82+
83+
- `configs`: tool configuration definitions that include both shared and project settings. Tools with no configuration are omitted.
84+
- `filePath`: the loaded configuration file's path, or `null` if no file was found.
85+
- `dependencies`: the configuration's dependencies, as reported by the loader.
86+
87+
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.
88+
89+
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.
90+
91+
`rstack/config` also exports the `Configs`, `LoadedRstackConfig`, and `LoadRstackConfigOptions` types.
92+
2893
## Re-exports
2994

3095
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.

‎website/docs/en/guide/testing.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,48 @@ define.test({
107107

108108
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.
109109

110+
### Shared test configurations
111+
112+
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.
113+
114+
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.
115+
116+
`define.extends()` and Rstest's `test.extends` serve different purposes: the former shares settings across tools; the latter controls Rstest's own configuration inheritance.
117+
118+
```ts title="shared.ts"
119+
import type { RstackConfig } from 'rstack';
120+
121+
export const sharedConfig: RstackConfig = {
122+
app: {
123+
resolve: {
124+
alias: {
125+
'@': './src',
126+
},
127+
},
128+
},
129+
test: {
130+
retry: 2,
131+
},
132+
};
133+
```
134+
135+
```ts title="rstack.config.ts"
136+
import { define } from 'rstack';
137+
import { sharedConfig } from './shared.ts';
138+
139+
define.extends([sharedConfig]);
140+
141+
define.test({
142+
testEnvironment: 'happy-dom',
143+
});
144+
```
145+
146+
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.
147+
148+
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.
149+
150+
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.
151+
110152
## Multiple projects
111153

112154
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.

‎website/docs/zh/guide/api-reference.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
1111
| 导入路径 | 内容 | 使用场景 |
1212
| ------------------------ | ----------------------------------------- | ------------------------ |
1313
| `rstack` | Rstack CLI 配置 API | 注册各项工具配置 |
14+
| `rstack/config` | 配置加载器及其类型 | 加载公共配置和项目配置 |
1415
| `rstack/app` | `@rsbuild/core` 的公开 API | 构建应用及扩展 Rsbuild |
1516
| `rstack/lib` | `@rslib/core` 的公开 API | 构建库及扩展 Rslib |
1617
| `rstack/test` | `@rstest/core` 的公开 API | 编写测试及配置测试项目 |
@@ -25,6 +26,70 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild
2526

2627
从 `rstack` 导入 `define`，用于在 `rstack.config.ts` 中注册各项工具配置；详细用法请参阅[配置 API](./configuration#configuration-apis)。
2728

29+
### `define.extends()` \{#define-extends}
30+
31+
继承公共配置，再应用项目自己的配置：
32+
33+
```ts
34+
import { define } from 'rstack';
35+
import { sharedConfig } from './shared.ts';
36+
37+
define.extends([sharedConfig]);
38+
```
39+
40+
- **类型：** `(configs: readonly RstackConfig[]) => void`
41+
- 传入配置对象数组。如果预设是函数，请先调用它，再传入返回的对象。
42+
- 每次加载配置时最多调用一次，传入空数组也算一次调用。
43+
- 先从左到右应用公共配置，再应用项目的 `define.*()` 配置，与调用顺序无关。
44+
45+
嵌套继承、合并规则和示例请参阅[公共配置](./configuration#shared-configurations)。
46+
47+
### `RstackConfig`
48+
49+
使用这个类型定义公共配置。所有字段均为可选：`app`、`lib`、`doc`、`test`、`lint`、`fmt` 和 `staged` 的用法与对应的 `define.*()` API 一致。需要继承其他公共配置时，可以添加类型为 `readonly RstackConfig[]` 的 `extends` 字段。
50+
51+
```ts
52+
import type { RstackConfig } from 'rstack';
53+
54+
export const sharedConfig: RstackConfig = {
55+
fmt: {
56+
singleQuote: true,
57+
},
58+
};
59+
```
60+
61+
## 加载配置 \{#loading-configurations}
62+
63+
### `loadRstackConfig()` \{#loadrstackconfig}
64+
65+
从 `rstack/config` 导入 `loadRstackConfig`，以编程方式加载配置：
66+
67+
```ts
68+
import { loadRstackConfig } from 'rstack/config';
69+
70+
const { configs, filePath, dependencies } = await loadRstackConfig({
71+
cwd: process.cwd(),
72+
configFilePath: './rstack.config.ts',
73+
});
74+
```
75+
76+
两个选项均可省略：
77+
78+
- `cwd`：用于查找配置文件和解析相对配置文件路径的目录，默认为当前工作目录。
79+
- `configFilePath`：配置文件的相对或绝对路径。省略时，优先使用 CLI 的 `--config` 路径；如果未设置，则在 `cwd` 中查找[默认配置文件名](./configuration#configuration-file)。
80+
81+
返回对象包含：
82+
83+
- `configs`：包含公共配置和项目配置的工具配置定义。未配置的工具不会出现在该对象中。
84+
- `filePath`：加载的配置文件路径，未找到文件时为 `null`。
85+
- `dependencies`：加载器报告的配置依赖。
86+
87+
加载器不会执行配置函数。即使某个工具的配置全部以对象形式传入，返回的字段也可能是异步函数，以便在需要该工具时再合并这些对象。
88+
89+
使用返回结果时，需要按各工具的要求传入参数、解析配置，再执行相应的初始化和运行流程。Rstack 的测试自动继承和格式化配置标准化也需要在这个阶段完成。`staged` 函数用于生成任务，应在运行任务时传入暂存文件名。
90+
91+
`rstack/config` 还导出 `Configs`、`LoadedRstackConfig` 和 `LoadRstackConfigOptions` 类型。
92+
2893
## 重导出 \{#re-exports}
2994

3095
以下工具子路径均会重导出对应 core 包的公开 API。通过这些入口导入，可以统一依赖入口，并确保 API 与 Rstack CLI 集成的工具版本匹配。

‎website/docs/zh/guide/testing.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,48 @@ define.test({
107107

108108
使用多项目配置时，在 `define.test()` 根配置中设置 `extends` 会关闭所有项目的自动继承；在某个内联项目中设置 `extends` 则只会关闭该项目的自动继承。
109109

110+
### 公共测试配置 \{#shared-test-configurations}
111+
112+
[公共配置](./configuration#shared-configurations) 可以同时提供构建和测试配置。Rstack 会先将它们与项目配置合并，再判断测试是否需要继承构建配置。
113+
114+
Rstack 首先使用 `mergeRstestConfig` 合并测试配置，再检查合并结果中的 `extends` 和 `projects`。需要自动继承的测试会使用合并后的 App 配置；没有定义 App 配置时，则使用合并后的 Lib 配置。
115+
116+
`define.extends()` 用于在多个工具之间共享配置，Rstest 的 `test.extends` 则控制测试配置自身的继承，两者用途不同。
117+
118+
```ts title="shared.ts"
119+
import type { RstackConfig } from 'rstack';
120+
121+
export const sharedConfig: RstackConfig = {
122+
app: {
123+
resolve: {
124+
alias: {
125+
'@': './src',
126+
},
127+
},
128+
},
129+
test: {
130+
retry: 2,
131+
},
132+
};
133+
```
134+
135+
```ts title="rstack.config.ts"
136+
import { define } from 'rstack';
137+
import { sharedConfig } from './shared.ts';
138+
139+
define.extends([sharedConfig]);
140+
141+
define.test({
142+
testEnvironment: 'happy-dom',
143+
});
144+
```
145+
146+
测试会在 happy-dom 中运行，使用 `retry: 2`，并继承公共 App 配置中的 `@` 别名。项目中无需再调用 `define.app()`。
147+
148+
如果要关闭自动继承，请在测试配置中显式设置 `extends`。在公共配置中设置也同样有效：只要合并后的测试配置包含 `extends`，即使值为 `undefined`，自动继承也会关闭。
149+
150+
使用多项目配置时，Rstack 会逐一检查合并后的内联项目。字符串形式的外部项目仍独立加载自己的配置。如果所有项目都不需要自动继承，Rstack 就会跳过 App 和 Lib 配置函数。
151+
110152
## 多项目 \{#multiple-projects}
111153

112154
通过 Rstest 的 [`projects`](https://rstest.rs/zh/config/test/projects) 选项可以同时运行多套测试配置。每一项既可以是内联项目，也可以是由 Rstest 解析为外部项目的字符串。

0 commit comments

Comments
 (0)