diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx index 4a28006e..e5f132e9 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,36 @@ 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} + +Use `loadRstackConfig()` from `rstack/config` to load Rstack configurations in your own code: + +```ts +import { loadRstackConfig } from 'rstack/config'; + +const { configs, filePath, dependencies } = await loadRstackConfig({ + cwd: process.cwd(), + configFilePath: './rstack.config.ts', +}); +``` + +The function accepts these optional parameters: + +- `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 has these fields: + +- `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. + +`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. + ## 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..f05ba888 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,36 @@ import { js, reactPlugin, ts } from 'rstack/lint'; 可用的预设和插件请参阅 [Rslint 规则和预设](https://rslint.rs/config/rules-and-presets)。 +## 加载配置 \{#loading-configurations} + +### `loadRstackConfig()` \{#loadrstackconfig} + +使用 `rstack/config` 导出的 `loadRstackConfig()`,可以在代码中加载 Rstack 配置: + +```ts +import { loadRstackConfig } from 'rstack/config'; + +const { configs, filePath, dependencies } = await loadRstackConfig({ + cwd: process.cwd(), + configFilePath: './rstack.config.ts', +}); +``` + +支持以下可选参数: + +- `cwd`:查找配置文件的目录。`configFilePath` 为相对路径时,也以此目录为基准。默认为当前工作目录。 +- `configFilePath`:配置文件路径,可以是相对路径或绝对路径。省略时,优先使用 CLI 通过 `--config` 指定的路径;若也未指定,则在 `cwd` 中按[默认文件名](./configuration#configuration-file)查找配置。 + +返回对象包含以下字段: + +- `configs`:各工具的配置对象或函数,包含项目配置及继承的[公共配置](./configuration#shared-configurations)。 +- `filePath`:加载的配置文件路径,未找到文件时为 `null`。 +- `dependencies`:加载器收集到的配置依赖路径列表。 + +`loadRstackConfig()` 仅负责加载配置,不会执行工具配置函数。调用方仍需完成相应工具的配置解析和初始化,才能运行工具。 + +`rstack/config` 还导出相关类型:`LoadRstackConfigOptions`(参数)、`LoadedRstackConfig`(返回值)和 `Configs`(工具配置)。 + ## TypeScript 类型 \{#typescript-types} 以下纯类型入口用于为 TypeScript 项目补充环境类型声明。请仅将项目需要的入口添加到 `tsconfig.json` 的 [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) 中。