diff --git a/website/docs/en/guide/api-reference.mdx b/website/docs/en/guide/api-reference.mdx index 4a28006e..d8d7045e 100644 --- a/website/docs/en/guide/api-reference.mdx +++ b/website/docs/en/guide/api-reference.mdx @@ -25,6 +25,36 @@ 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. +### `RstackConfig` + +`RstackConfig` is the type for a [shared configuration](./configuration#shared-configurations). All fields are optional, so include only the settings you want to share. + +Each tool field accepts the same configuration as its corresponding `define.*()` method. For example, `fmt` accepts the same input as `define.fmt()`. + +```ts title="shared.ts" +import type { RstackConfig } from 'rstack'; + +export const sharedConfig: RstackConfig = { + fmt: { + singleQuote: true, + }, +}; +``` + +Use the `extends` field to inherit other shared configurations. Its type is `readonly RstackConfig[]`. + +```ts title="team.ts" +import type { RstackConfig } from 'rstack'; +import { sharedConfig } from './shared.ts'; + +export const teamConfig: RstackConfig = { + extends: [sharedConfig], + fmt: { + printWidth: 100, + }, +}; +``` + ## 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. diff --git a/website/docs/en/guide/configuration.mdx b/website/docs/en/guide/configuration.mdx index 29183e66..68844127 100644 --- a/website/docs/en/guide/configuration.mdx +++ b/website/docs/en/guide/configuration.mdx @@ -78,15 +78,16 @@ define.fmt({ 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. -| 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.fmt()`](#define-fmt) | [Prettier](https://prettier.io/docs/options) | [`rs fmt`](./cli/fmt) | -| [`define.staged()`](#define-staged) | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`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.fmt()`](#define-fmt) | [Prettier](https://prettier.io/docs/options) | [`rs fmt`](./cli/fmt) | +| [`define.staged()`](#define-staged) | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged) | +| [`define.extends()`](#define-extends) | — | — | ### `define.app()` \{#define-app} @@ -205,6 +206,14 @@ define.staged({ Provide a staged configuration through `define.staged()` or a [shared configuration](#shared-configurations). `rs staged` reports an error if neither provides one. +### `define.extends()` \{#define-extends} + +Accepts an array of shared configuration objects and applies their tool settings before merging the project's own `define.*()` configurations. + +**Type:** `(configs: readonly RstackConfig[]) => void` + +See [Shared configurations](#shared-configurations) for usage and merge rules. + ## Shared configurations Use `define.extends()` to share build, test, lint, and formatting settings across projects. A shared configuration is a plain object whose fields accept the same values as the corresponding `define.*()` APIs. In TypeScript, use `RstackConfig` to check its types: diff --git a/website/docs/en/guide/testing.mdx b/website/docs/en/guide/testing.mdx index db90404c..c5a11fa9 100644 --- a/website/docs/en/guide/testing.mdx +++ b/website/docs/en/guide/testing.mdx @@ -36,6 +36,8 @@ import { defineInlineProject, expect, test } from 'rstack/test'; When `define.test()` does not set Rstest's [`extends`](https://rstest.rs/config/test/extends), Rstack CLI automatically converts the configuration registered by `define.app()` or `define.lib()` into an Rstest configuration. The inherited configuration is merged with the options passed directly to `define.test()`. +When using [shared configurations](./configuration#shared-configurations), Rstack first merges the shared and project test settings, then determines whether automatic inheritance is needed. If it is, Rstack uses the merged App or Lib configuration. + ### Inherit the application configuration When `define.app()` is registered, Rstack CLI converts it with [`@rstest/adapter-rsbuild`](https://rstest.rs/guide/integration/rsbuild) and uses the result as the test configuration's `extends` value: diff --git a/website/docs/zh/guide/api-reference.mdx b/website/docs/zh/guide/api-reference.mdx index 16c373fc..75ec80f5 100644 --- a/website/docs/zh/guide/api-reference.mdx +++ b/website/docs/zh/guide/api-reference.mdx @@ -25,6 +25,36 @@ Rstack CLI 提供统一的配置 API，并通过专用子路径重导出 Rsbuild 从 `rstack` 导入 `define`，用于在 `rstack.config.ts` 中注册各项工具配置；详细用法请参阅[配置 API](./configuration#configuration-apis)。 +### `RstackConfig` + +`RstackConfig` 是[公共配置](./configuration#shared-configurations)的类型。所有字段均为可选，只需填写需要共享的配置。 + +各工具字段接受与对应 `define.*()` 方法相同的配置，例如 `fmt` 对应 `define.fmt()`。 + +```ts title="shared.ts" +import type { RstackConfig } from 'rstack'; + +export const sharedConfig: RstackConfig = { + fmt: { + singleQuote: true, + }, +}; +``` + +还可以通过 `extends` 字段继承其他公共配置，该字段的类型为 `readonly RstackConfig[]`。 + +```ts title="team.ts" +import type { RstackConfig } from 'rstack'; +import { sharedConfig } from './shared.ts'; + +export const teamConfig: RstackConfig = { + extends: [sharedConfig], + fmt: { + printWidth: 100, + }, +}; +``` + ## 重导出 \{#re-exports} 以下工具子路径均会重导出对应 core 包的公开 API。通过这些入口导入，可以统一依赖入口，并确保 API 与 Rstack CLI 集成的工具版本匹配。 diff --git a/website/docs/zh/guide/configuration.mdx b/website/docs/zh/guide/configuration.mdx index b0f3e9d0..ddcbfb7c 100644 --- a/website/docs/zh/guide/configuration.mdx +++ b/website/docs/zh/guide/configuration.mdx @@ -78,15 +78,16 @@ define.fmt({ 各 API 沿用底层工具的配置格式。使用 Rstack CLI 已重导出的 API 和辅助函数时，推荐从 `rstack/app`、`rstack/lib`、`rstack/test` 和 `rstack/lint` 入口导入。 -| 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.fmt()`](#define-fmt) | [Prettier](https://prettier.io/docs/options) | [`rs fmt`](./cli/fmt) | -| [`define.staged()`](#define-staged) | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`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.fmt()`](#define-fmt) | [Prettier](https://prettier.io/docs/options) | [`rs fmt`](./cli/fmt) | +| [`define.staged()`](#define-staged) | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](./cli/staged) | +| [`define.extends()`](#define-extends) | — | — | ### `define.app()` \{#define-app} @@ -205,6 +206,14 @@ define.staged({ 请通过 `define.staged()` 或[公共配置](#shared-configurations)提供 staged 配置，否则 `rs staged` 会报错。 +### `define.extends()` \{#define-extends} + +接收一组公共配置对象，先应用其中各工具的配置，再合并当前项目通过 `define.*()` 定义的配置。 + +**类型：** `(configs: readonly RstackConfig[]) => void` + +用法和合并规则请参阅[公共配置](#shared-configurations)。 + ## 公共配置 \{#shared-configurations} 使用 `define.extends()` 可以在多个项目之间共享构建、测试、lint 和格式化配置。公共配置是一个普通对象，各字段的用法与对应的 `define.*()` API 一致。在 TypeScript 中，可以用 `RstackConfig` 检查配置类型： diff --git a/website/docs/zh/guide/testing.mdx b/website/docs/zh/guide/testing.mdx index 43474a71..9aa005f6 100644 --- a/website/docs/zh/guide/testing.mdx +++ b/website/docs/zh/guide/testing.mdx @@ -36,6 +36,8 @@ import { defineInlineProject, expect, test } from 'rstack/test'; 当 `define.test()` 未设置 Rstest 的 [`extends`](https://rstest.rs/zh/config/test/extends) 时，Rstack CLI 会自动将 `define.app()` 或 `define.lib()` 注册的配置转换为 Rstest 配置，再与直接传给 `define.test()` 的选项合并。 +使用[公共配置](./configuration#shared-configurations)时，Rstack 会先合并公共配置和项目中的测试配置，再判断是否需要自动继承。需要继承时，使用合并后的 App 或 Lib 配置。 + ### 继承应用配置 \{#inherit-the-application-configuration} 注册 `define.app()` 后，Rstack CLI 会通过 [`@rstest/adapter-rsbuild`](https://rstest.rs/zh/guide/integration/rsbuild) 转换该配置，并将结果作为测试配置的 `extends`：