From 8e7cbfeb5720d641e825fe968f058d3f082a6c27 Mon Sep 17 00:00:00 2001 From: neverland Date: Fri, 9 Oct 2026 16:56:04 +0800 Subject: [PATCH 1/4] docs: document programmatic configuration loading --- website/docs/en/guide/api-reference.mdx | 33 +++++++++++++++++++++++++ website/docs/zh/guide/api-reference.mdx | 33 +++++++++++++++++++++++++ 2 files changed, 66 insertions(+) diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx index 4a28006e..efb35ab7 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 | @@ -71,6 +72,38 @@ import { js, reactPlugin, ts } from 'rstack/lint'; For details about the available presets and plugins, see [Rslint rules and presets](https://rslint.rs/config/rules-and-presets). +## 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. + ## TypeScript types These type-only entry points add ambient declarations to a TypeScript project. Add only the entries your project needs to [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) in `tsconfig.json`. diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx index 16c373fc..40d2a88e 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 | 编写测试及配置测试项目 | @@ -71,6 +72,38 @@ import { js, reactPlugin, ts } from 'rstack/lint'; 可用的预设和插件请参阅 [Rslint 规则和预设](https://rslint.rs/config/rules-and-presets)。 +## 加载配置 \{#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` 类型。 + ## TypeScript 类型 \{#typescript-types} 以下纯类型入口用于为 TypeScript 项目补充环境类型声明。请仅将项目需要的入口添加到 `tsconfig.json` 的 [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) 中。 From 0a77329224914f7d28292f031a9f9bdd0662f099 Mon Sep 17 00:00:00 2001 From: neverland Date: Fri, 9 Oct 2026 17:17:23 +0800 Subject: [PATCH 2/4] docs: clarify configuration loader reference --- website/docs/en/guide/api-reference.mdx | 22 ++++++++++++---------- website/docs/zh/guide/api-reference.mdx | 22 ++++++++++++---------- 2 files changed, 24 insertions(+), 20 deletions(-) diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx index efb35ab7..7f84632f 100644 --- a/website/docs/en/guide/api-reference.mdx +++ b/website/docs/en/guide/api-reference.mdx @@ -76,7 +76,7 @@ For details about the available presets and plugins, see [Rslint rules and prese ### `loadRstackConfig()` \{#loadrstackconfig} -Import `loadRstackConfig` from `rstack/config` to load configurations programmatically: +Use `loadRstackConfig()` from `rstack/config` to load Rstack configurations in your own code: ```ts import { loadRstackConfig } from 'rstack/config'; @@ -87,22 +87,24 @@ const { configs, filePath, dependencies } = await loadRstackConfig({ }); ``` -Both options are optional: +The function accepts these optional parameters: -- `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`. +- `cwd`: the directory to search for a configuration file. Relative `configFilePath` values are also resolved from this directory. Defaults to the current working directory. +- `configFilePath`: a relative or absolute path to the configuration file. If omitted, the loader uses the path specified by the CLI's `--config` option. If neither is set, it searches `cwd` for the [default file names](./configuration#configuration-file). -The returned object contains: +The returned object has these fields: -- `configs`: tool configuration definitions that include both shared and project settings. Tools with no configuration are omitted. +- `configs`: configuration objects or functions for each tool, including project settings and inherited [shared configurations](./configuration#shared-configurations). 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. +- `dependencies`: paths to configuration dependencies collected 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. +The loader does not run tool configuration functions. When several configurations need to be merged, it may return an async function even if the original configurations were all objects. The merge runs when that function is called. -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. +Your code still needs to pass the parameters each tool expects, resolve its configuration, and run the tool. Automatic test inheritance and formatting normalization do not run during loading. -`rstack/config` also exports the `Configs`, `LoadedRstackConfig`, and `LoadRstackConfigOptions` types. +Functions in `staged` generate tasks from file lists. They are called by lint-staged when tasks run. + +`rstack/config` also exports the related types: `LoadRstackConfigOptions` for the parameters, `LoadedRstackConfig` for the return value, and `Configs` for the tool configurations. ## TypeScript types diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx index 40d2a88e..3a1ce277 100644 --- a/website/docs/zh/guide/api-reference.mdx +++ b/website/docs/zh/guide/api-reference.mdx @@ -76,7 +76,7 @@ import { js, reactPlugin, ts } from 'rstack/lint'; ### `loadRstackConfig()` \{#loadrstackconfig} -从 `rstack/config` 导入 `loadRstackConfig`，以编程方式加载配置： +使用 `rstack/config` 导出的 `loadRstackConfig()`，可以在代码中加载 Rstack 配置： ```ts import { loadRstackConfig } from 'rstack/config'; @@ -87,22 +87,24 @@ const { configs, filePath, dependencies } = await loadRstackConfig({ }); ``` -两个选项均可省略： +支持以下可选参数： -- `cwd`：用于查找配置文件和解析相对配置文件路径的目录，默认为当前工作目录。 -- `configFilePath`：配置文件的相对或绝对路径。省略时，优先使用 CLI 的 `--config` 路径；如果未设置，则在 `cwd` 中查找[默认配置文件名](./configuration#configuration-file)。 +- `cwd`：查找配置文件的目录。`configFilePath` 为相对路径时，也以此目录为基准。默认为当前工作目录。 +- `configFilePath`：配置文件路径，可以是相对路径或绝对路径。省略时，优先使用 CLI 通过 `--config` 指定的路径；若也未指定，则在 `cwd` 中按[默认文件名](./configuration#configuration-file)查找配置。 -返回对象包含： +返回对象包含以下字段： -- `configs`：包含公共配置和项目配置的工具配置定义。未配置的工具不会出现在该对象中。 +- `configs`：各工具的配置对象或函数，包含项目配置及继承的[公共配置](./configuration#shared-configurations)。未配置的工具会被省略。 - `filePath`：加载的配置文件路径，未找到文件时为 `null`。 -- `dependencies`：加载器报告的配置依赖。 +- `dependencies`：加载器收集到的配置依赖路径列表。 -加载器不会执行配置函数。即使某个工具的配置全部以对象形式传入，返回的字段也可能是异步函数，以便在需要该工具时再合并这些对象。 +加载时不会执行工具配置函数。需要合并多份配置时，返回值可能是一个异步函数，即使原始配置都是对象。调用该函数时才会执行合并。 -使用返回结果时，需要按各工具的要求传入参数、解析配置，再执行相应的初始化和运行流程。Rstack 的测试自动继承和格式化配置标准化也需要在这个阶段完成。`staged` 函数用于生成任务，应在运行任务时传入暂存文件名。 +调用方仍需按各工具的要求传入参数、解析配置并运行工具。测试自动继承、格式化配置标准化等步骤不会在加载时执行。 -`rstack/config` 还导出 `Configs`、`LoadedRstackConfig` 和 `LoadRstackConfigOptions` 类型。 +`staged` 中的函数用于根据文件列表生成任务，由 lint-staged 在运行时调用。 + +`rstack/config` 还导出相关类型：`LoadRstackConfigOptions`（参数）、`LoadedRstackConfig`（返回值）和 `Configs`（工具配置）。 ## TypeScript 类型 \{#typescript-types} From ad4f4efc03171dddb74bd7c5d312f007ea4ff201 Mon Sep 17 00:00:00 2001 From: neverland Date: Fri, 9 Oct 2026 17:22:38 +0800 Subject: [PATCH 3/4] docs: remove redundant omitted configuration note --- 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 7f84632f..bbfdb622 100644 --- a/website/docs/en/guide/api-reference.mdx +++ b/website/docs/en/guide/api-reference.mdx @@ -94,7 +94,7 @@ The function accepts these optional parameters: The returned object has these fields: -- `configs`: configuration objects or functions for each tool, including project settings and inherited [shared configurations](./configuration#shared-configurations). Tools with no configuration are omitted. +- `configs`: configuration objects or functions for each tool, including project settings and inherited [shared configurations](./configuration#shared-configurations). - `filePath`: the loaded configuration file's path, or `null` if no file was found. - `dependencies`: paths to configuration dependencies collected by the loader. diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx index 3a1ce277..2ae477cf 100644 --- a/website/docs/zh/guide/api-reference.mdx +++ b/website/docs/zh/guide/api-reference.mdx @@ -94,7 +94,7 @@ const { configs, filePath, dependencies } = await loadRstackConfig({ 返回对象包含以下字段： -- `configs`：各工具的配置对象或函数，包含项目配置及继承的[公共配置](./configuration#shared-configurations)。未配置的工具会被省略。 +- `configs`：各工具的配置对象或函数，包含项目配置及继承的[公共配置](./configuration#shared-configurations)。 - `filePath`：加载的配置文件路径，未找到文件时为 `null`。 - `dependencies`：加载器收集到的配置依赖路径列表。 From 39d3b97a9159425d37e87745d69fa6d08fcc24ad Mon Sep 17 00:00:00 2001 From: neverland Date: Fri, 9 Oct 2026 17:27:56 +0800 Subject: [PATCH 4/4] docs: simplify configuration loading boundaries --- website/docs/en/guide/api-reference.mdx | 6 +----- website/docs/zh/guide/api-reference.mdx | 6 +----- 2 files changed, 2 insertions(+), 10 deletions(-) diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx index bbfdb622..e5f132e9 100644 --- a/website/docs/en/guide/api-reference.mdx +++ b/website/docs/en/guide/api-reference.mdx @@ -98,11 +98,7 @@ The returned object has these fields: - `filePath`: the loaded configuration file's path, or `null` if no file was found. - `dependencies`: paths to configuration dependencies collected by the loader. -The loader does not run tool configuration functions. When several configurations need to be merged, it may return an async function even if the original configurations were all objects. The merge runs when that function is called. - -Your code still needs to pass the parameters each tool expects, resolve its configuration, and run the tool. Automatic test inheritance and formatting normalization do not run during loading. - -Functions in `staged` generate tasks from file lists. They are called by lint-staged when tasks run. +`loadRstackConfig()` only loads configurations; it does not run tool configuration functions. Before running a tool, the caller must resolve its configuration and initialize it. `rstack/config` also exports the related types: `LoadRstackConfigOptions` for the parameters, `LoadedRstackConfig` for the return value, and `Configs` for the tool configurations. diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx index 2ae477cf..f05ba888 100644 --- a/website/docs/zh/guide/api-reference.mdx +++ b/website/docs/zh/guide/api-reference.mdx @@ -98,11 +98,7 @@ const { configs, filePath, dependencies } = await loadRstackConfig({ - `filePath`：加载的配置文件路径，未找到文件时为 `null`。 - `dependencies`：加载器收集到的配置依赖路径列表。 -加载时不会执行工具配置函数。需要合并多份配置时，返回值可能是一个异步函数，即使原始配置都是对象。调用该函数时才会执行合并。 - -调用方仍需按各工具的要求传入参数、解析配置并运行工具。测试自动继承、格式化配置标准化等步骤不会在加载时执行。 - -`staged` 中的函数用于根据文件列表生成任务，由 lint-staged 在运行时调用。 +`loadRstackConfig()` 仅负责加载配置，不会执行工具配置函数。调用方仍需完成相应工具的配置解析和初始化，才能运行工具。 `rstack/config` 还导出相关类型：`LoadRstackConfigOptions`（参数）、`LoadedRstackConfig`（返回值）和 `Configs`（工具配置）。