From 039eff859dc764b75a2910ceab4b24ea0107c055 Mon Sep 17 00:00:00 2001 From: neverland Date: Mon, 20 Jul 2026 19:05:10 +0800 Subject: [PATCH] docs: complete configuration guide --- website/docs/en/guide/configuration.mdx | 170 +++++++++++++++++++++--- website/docs/zh/guide/configuration.mdx | 170 +++++++++++++++++++++--- 2 files changed, 296 insertions(+), 44 deletions(-) diff --git a/website/docs/en/guide/configuration.mdx b/website/docs/en/guide/configuration.mdx index 307cc17..0c3521d 100644 --- a/website/docs/en/guide/configuration.mdx +++ b/website/docs/en/guide/configuration.mdx @@ -1,43 +1,169 @@ # Configuration -TODO. +Rstack centralizes the configuration for your project's tools in a single file. Define only the configurations your project needs with the `define.*()` APIs. -## `define.app()` \{#define-app} +## Configuration file -TODO. +Create `rstack.config.ts` in the project root and call the relevant `define.*()` APIs: -Commands: +```ts title="rstack.config.ts" +import { define } from 'rstack'; -- [`rs dev`](./cli/dev) -- [`rs build`](./cli/build) -- [`rs preview`](./cli/preview) +define.app({ + // Rsbuild configuration +}); -## `define.lib()` \{#define-lib} +define.test({ + // Rstest configuration +}); +``` -TODO. +The configuration file does not require a default export. Each `define.*()` API can be called at most once; defining the same configuration type more than once throws an error. -Command: [`rs lib`](./cli/lib). +By default, Rstack looks for a file with one of the following names: -## `define.doc()` \{#define-doc} +- `rstack.config.ts` +- `rstack.config.js` +- `rstack.config.mts` +- `rstack.config.mjs` -TODO. +All `rs` commands accept the global `-c, --config` option for loading a file with a different name or location: -Command: [`rs doc`](./cli/doc). +```bash +rs build --config ./configs/rstack.config.ts +``` -## `define.test()` \{#define-test} +## Loading dependencies on demand -TODO. +Every `rs` command loads and executes the Rstack configuration file, then resolves only the configuration functions needed by that command. -Command: [`rs test`](./cli/test). +When a configuration needs to import plugins or other tool-specific dependencies, use an async configuration function and load those dependencies with dynamic `import()` inside it. This ensures that they are loaded only when the configuration is resolved. -## `define.lint()` \{#define-lint} +```ts title="rstack.config.ts" +import { define } from 'rstack'; -TODO. +define.app(async () => { + const { pluginReact } = await import('@rsbuild/plugin-react'); -Command: [`rs lint`](./cli/lint). + return { + plugins: [pluginReact()], + }; +}); +``` -## `define.staged()` \{#define-staged} +## Configuration APIs -TODO. +Configuration options follow the formats of the underlying tools. When using APIs and helpers that Rstack re-exports, prefer the `rstack/app`, `rstack/lib`, `rstack/test`, and `rstack/lint` entry points. -Command: [`rs staged`](./cli/staged). +| 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.staged()`](#define-staged) | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged) | + +### `define.app()` \{#define-app} + +Defines the [Rsbuild configuration](https://rsbuild.rs/config/) for an application. It accepts a configuration object or a configuration function. The function receives the standard Rsbuild configuration parameters. + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.app({ + html: { + title: 'My App', + }, + output: { + distPath: { + root: 'dist', + }, + }, +}); +``` + +### `define.lib()` \{#define-lib} + +Defines the [Rslib configuration](https://rslib.rs/config/) for a library. It accepts a configuration object or a configuration function. The function receives the standard Rslib configuration parameters. + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.lib({ + lib: [ + { + dts: true, + format: 'esm', + }, + ], +}); +``` + +### `define.doc()` \{#define-doc} + +Defines the [Rspress configuration](https://rspress.rs/api/config/config-basic) for a documentation site. It accepts a configuration object or an async configuration function. + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.doc({ + root: 'docs', + title: 'My Site', +}); +``` + +`@rspress/core` is an optional dependency of Rstack. Install it in every project that uses the `rs doc` command: + +```bash +pnpm add -D @rspress/core +``` + +### `define.test()` \{#define-test} + +Defines the [Rstest configuration](https://rstest.rs/config/). It accepts a configuration object or a configuration function. + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.app({ + // Shared application configuration +}); + +define.test({ + setupFiles: ['./tests/rstest.setup.ts'], + testEnvironment: 'happy-dom', +}); +``` + +When `extends` is omitted, Rstack automatically connects the test configuration to `define.app()` through the Rsbuild adapter. If no application configuration is defined, it falls back to `define.lib()` through the Rslib adapter. The application configuration takes precedence when both are defined. Set `extends` explicitly to opt out of this automatic inheritance. + +If the root test configuration does not define `extends` and contains `projects`, Rstack 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. + +### `define.lint()` \{#define-lint} + +Defines the [Rslint configuration](https://rslint.rs/config/). Pass the configuration directly, or use an async function to load presets and plugins from `rstack/lint` on demand. + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.lint(async () => { + const { js, ts } = await import('rstack/lint'); + + return [js.configs.recommended, ts.configs.recommended]; +}); +``` + +### `define.staged()` \{#define-staged} + +Defines the [lint-staged configuration](https://github.com/lint-staged/lint-staged#configuration) used to run tasks on staged Git files. It accepts either an object that maps glob patterns to tasks or a task-generator function. Tasks can be commands, command arrays, or functions supported by lint-staged. + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.staged({ + '*.{js,jsx,ts,tsx}': 'rs lint', +}); +``` + +Unlike the other commands, `rs staged` requires a `define.staged()` configuration and reports an error when it is missing. diff --git a/website/docs/zh/guide/configuration.mdx b/website/docs/zh/guide/configuration.mdx index c67524c..f00a463 100644 --- a/website/docs/zh/guide/configuration.mdx +++ b/website/docs/zh/guide/configuration.mdx @@ -1,43 +1,169 @@ # 配置 -TODO. +Rstack 将项目所用工具的配置集中到一份文件中。通过 `define.*()` API 定义项目实际需要的配置即可。 -## `define.app()` \{#define-app} +## 配置文件 -TODO. +在项目根目录创建 `rstack.config.ts`，并调用对应的 `define.*()` API： -对应命令： +```ts title="rstack.config.ts" +import { define } from 'rstack'; -- [`rs dev`](./cli/dev) -- [`rs build`](./cli/build) -- [`rs preview`](./cli/preview) +define.app({ + // Rsbuild 配置 +}); -## `define.lib()` \{#define-lib} +define.test({ + // Rstest 配置 +}); +``` -TODO. +配置文件无需默认导出。每个 `define.*()` API 最多调用一次；重复定义同一类型的配置会抛出错误。 -对应命令：[`rs lib`](./cli/lib)。 +Rstack 默认会查找使用以下任一文件名的配置文件： -## `define.doc()` \{#define-doc} +- `rstack.config.ts` +- `rstack.config.js` +- `rstack.config.mts` +- `rstack.config.mjs` -TODO. +所有 `rs` 命令都支持全局的 `-c, --config` 选项，用于加载其他名称或位置的配置文件： -对应命令：[`rs doc`](./cli/doc)。 +```bash +rs build --config ./configs/rstack.config.ts +``` -## `define.test()` \{#define-test} +## 按需加载依赖 -TODO. +每次执行 `rs` 命令时，Rstack 都会加载并执行配置文件，然后只解析当前命令需要的配置函数。 -对应命令：[`rs test`](./cli/test)。 +如果配置需要导入插件或其他工具专属依赖，请使用异步配置函数，并在函数内通过动态 `import()` 加载这些依赖。这样只有解析该配置时才会加载相关依赖。 -## `define.lint()` \{#define-lint} +```ts title="rstack.config.ts" +import { define } from 'rstack'; -TODO. +define.app(async () => { + const { pluginReact } = await import('@rsbuild/plugin-react'); -对应命令：[`rs lint`](./cli/lint)。 + return { + plugins: [pluginReact()], + }; +}); +``` -## `define.staged()` \{#define-staged} +## 配置 API -TODO. +各 API 沿用底层工具的配置格式。使用 Rstack 已重导出的 API 和辅助函数时，推荐从 `rstack/app`、`rstack/lib`、`rstack/test` 和 `rstack/lint` 入口导入。 -对应命令：[`rs staged`](./cli/staged)。 +| 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.staged()`](#define-staged) | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged) | + +### `define.app()` \{#define-app} + +定义应用的 [Rsbuild 配置](https://rsbuild.rs/zh/config/)，支持传入配置对象或配置函数。配置函数接收 Rsbuild 的标准配置参数。 + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.app({ + html: { + title: 'My App', + }, + output: { + distPath: { + root: 'dist', + }, + }, +}); +``` + +### `define.lib()` \{#define-lib} + +定义库的 [Rslib 配置](https://rslib.rs/zh/config/)，支持传入配置对象或配置函数。配置函数接收 Rslib 的标准配置参数。 + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.lib({ + lib: [ + { + dts: true, + format: 'esm', + }, + ], +}); +``` + +### `define.doc()` \{#define-doc} + +定义文档站点的 [Rspress 配置](https://rspress.rs/zh/api/config/config-basic)，支持传入配置对象或异步配置函数。 + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.doc({ + root: 'docs', + title: 'My Site', +}); +``` + +`@rspress/core` 是 Rstack 的可选依赖。每个使用 `rs doc` 命令的项目都需要安装该依赖： + +```bash +pnpm add -D @rspress/core +``` + +### `define.test()` \{#define-test} + +定义 [Rstest 配置](https://rstest.rs/zh/config/)，支持传入配置对象或配置函数。 + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.app({ + // 共享的应用配置 +}); + +define.test({ + setupFiles: ['./tests/rstest.setup.ts'], + testEnvironment: 'happy-dom', +}); +``` + +未设置 `extends` 时，Rstack 会通过 Rsbuild 适配器让测试配置自动继承 `define.app()`；如果未定义应用配置，则通过 Rslib 适配器回退到 `define.lib()`。二者同时存在时，应用配置的优先级更高。显式设置 `extends` 可关闭自动继承。 + +如果测试根配置未定义 `extends` 且包含 `projects`，Rstack 会为每个未自行设置 `extends` 的内联项目应用自动继承。函数形式的应用或库配置只会解析一次，并由这些项目共享。字符串形式的项目会原样传给 Rstest；它们会独立加载外部配置，不继承当前应用或库的配置。 + +### `define.lint()` \{#define-lint} + +定义 [Rslint 配置](https://rslint.rs/config/)。可以直接传入配置，也可以使用异步函数，按需从 `rstack/lint` 加载预设和插件。 + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.lint(async () => { + const { js, ts } = await import('rstack/lint'); + + return [js.configs.recommended, ts.configs.recommended]; +}); +``` + +### `define.staged()` \{#define-staged} + +定义用于处理 Git 暂存文件的 [lint-staged 配置](https://github.com/lint-staged/lint-staged#configuration)。支持传入从 glob 匹配模式映射到任务的配置对象，也支持传入任务生成函数。任务可以是 lint-staged 支持的命令、命令数组或函数。 + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.staged({ + '*.{js,jsx,ts,tsx}': 'rs lint', +}); +``` + +与其他命令不同，`rs staged` 必须配置 `define.staged()`；缺少配置时会报错。