> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 配置 \{#configuration}

Rstack CLI 将项目所用工具的配置集中到一份文件中。通过 `define.*()` API 定义项目实际需要的配置即可。

## 配置文件 \{#configuration-file}

在项目根目录创建 `rstack.config.ts`，并调用对应的 `define.*()` API：

```ts title="rstack.config.ts"
// Configuration guide: https://rstack.rs/config
import { define } from 'rstack';

define.app({
  // Rsbuild 配置
});

define.test({
  // Rstest 配置
});

define.lint({
  // Rslint 配置
});

define.fmt({
  // 格式化配置
});
```

配置文件无需默认导出。每个 `define.*()` API 最多调用一次；重复定义同一类型的配置会抛出错误。

Rstack CLI 默认会查找使用以下任一文件名的配置文件：

- `rstack.config.ts`
- `rstack.config.js`
- `rstack.config.mts`
- `rstack.config.mjs`

所有 `rs` 命令都支持全局的 `-c, --config` 选项，用于加载其他名称或位置的配置文件：

```bash
rs build --config ./configs/rstack.config.ts
```

## 导入依赖 \{#loading-dependencies-on-demand}

Rstack 将项目的构建、测试、代码检查、格式化等配置集中在一个 `rstack.config.*` 文件中。命令加载配置文件时，会同时加载所有顶层 `import`，即使当前命令用不到对应的配置。因此，在顶层导入所有工具和插件可能会增加 `rs lint`、`rs fmt` 等命令的启动开销。

请根据配置内容选择导入方式：

- 如果配置只用于一个应用及其测试、一个库及其测试或一个文档站点，优先使用更简洁的静态导入。
- 如果同一配置还包含 lint、格式化或暂存文件检查，可在相应的异步配置函数中动态导入依赖，让检查命令跳过这些依赖。

```ts title="rstack.config.ts"
import { define } from 'rstack';

define.app(async () => {
  const { pluginReact } = await import('@rsbuild/plugin-react');
  return {
    plugins: [pluginReact()],
  };
});

define.lint(({ js }) => [js.configs.recommended]);

define.fmt({
  singleQuote: true,
});
```

## 配置 API \{#configuration-apis}

各 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`](/zh/guide/cli/dev.md)、[`rs build`](/zh/guide/cli/build.md)、[`rs preview`](/zh/guide/cli/preview.md) |
| [`define.lib()`](#define-lib)       | [Rslib](https://rslib.rs/zh/config/)                                    | [`rs lib`](/zh/guide/cli/lib.md)                                                                               |
| [`define.doc()`](#define-doc)       | [Rspress](https://rspress.rs/zh/api/config/config-basic)                | [`rs doc`](/zh/guide/cli/doc.md)                                                                               |
| [`define.test()`](#define-test)     | [Rstest](https://rstest.rs/zh/config/)                                  | [`rs test`](/zh/guide/cli/test.md)                                                                             |
| [`define.lint()`](#define-lint)     | [Rslint](https://rslint.rs/config/)                                     | [`rs lint`](/zh/guide/cli/lint.md)                                                                             |
| [`define.fmt()`](#define-fmt)       | [Prettier](https://prettier.io/docs/options)                            | [`rs fmt`](/zh/guide/cli/fmt.md)                                                                               |
| [`define.staged()`](#define-staged) | [lint-staged](https://github.com/lint-staged/lint-staged#configuration) | [`rs staged`](/zh/guide/cli/staged.md)                                                                         |

### `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({
  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 CLI 的可选依赖。每个使用 `rs doc` 命令的项目都需要安装该依赖：


```sh [npm]
npm install -D @rspress/core
```

```sh [yarn]
yarn add -D @rspress/core
```

```sh [pnpm]
pnpm add -D @rspress/core
```

```sh [bun]
bun add -D @rspress/core
```

```sh [deno]
deno add -D npm:@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 CLI 会通过 Rsbuild 适配器让测试配置自动继承 `define.app()`；如果未定义应用配置，则通过 Rslib 适配器回退到 `define.lib()`。二者同时存在时，应用配置的优先级更高。显式设置 `extends` 可关闭自动继承。

如果测试根配置未定义 `extends` 且包含 `projects`，Rstack CLI 会为每个未自行设置 `extends` 的内联项目应用自动继承。函数形式的应用或库配置只会解析一次，并由这些项目共享。字符串形式的项目会原样传给 Rstest；它们会独立加载外部配置，不继承当前应用或库的配置。

> 如需了解更多测试相关用法，请参阅[测试](/zh/guide/testing.md)。

### `define.lint()` \{#define-lint}

定义 [Rslint 配置](https://rslint.rs/config/)。可以直接传入配置，也可以传入同步或异步函数。函数会接收 `rstack/lint` 的全部导出，因此无需手动导入预设和插件。

```ts title="rstack.config.ts"
import { define } from 'rstack';

define.lint(({ js, ts }) => [
  js.configs.recommended,
  ts.configs.recommendedTypeChecked,
]);
```

### `define.fmt()` \{#define-fmt}

定义 [`rs fmt`](/zh/guide/cli/fmt.md) 的格式化配置。可以直接传入配置对象，也可以传入返回配置对象的同步或异步函数。

```ts title="rstack.config.ts"
import { define } from 'rstack';

define.fmt({
  printWidth: 100,
  singleQuote: true,
});
```

详细用法请参考[格式化](/zh/guide/formatting.md)指南。

### `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 fmt'],
  '*.{json,jsonc,md,mdx,css,html,yml,yaml}': 'rs fmt',
});
```

与其他命令不同，`rs staged` 必须配置 `define.staged()`；缺少配置时会报错。