---
url: /zh/guide/quick-start.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/quick-start.md.

# 快速上手 \{#quick-start}

Rstack CLI 通过统一的命令行和配置文件整合 Rstack 工具链。本指南将介绍如何在现有项目中添加 Rstack，以及可以使用的工作流。

## 环境准备 \{#environment-preparation}

Rstack 支持使用 [Node.js](https://nodejs.org/)、[Deno](https://deno.com/) 或 [Bun](https://bun.sh/) 作为 JavaScript 运行时。

参考以下安装指南，选择一种运行时：

- [安装 Node.js](https://nodejs.org/zh-cn/download)
- [安装 Bun](https://bun.com/docs/installation)
- [安装 Deno](https://docs.deno.com/runtime/getting_started/installation/)

:::tip 版本要求

使用 Node.js 作为运行时时，Rstack 要求 Node.js 版本为 22.12.0 或更高版本。

:::

## 安装 Rstack \{#install-rstack}

在已有 `package.json` 的项目中，将 [`rstack`](https://www.npmjs.com/package/rstack) 安装为开发依赖：


```sh [npm]
npm install -D rstack
```

```sh [yarn]
yarn add -D rstack
```

```sh [pnpm]
pnpm add -D rstack
```

```sh [bun]
bun add -d rstack
```

## CLI 命令 \{#cli-commands}

在 `package.json` 的 `scripts` 字段中添加项目所需的命令，例如：

```json title="package.json"
{
  "scripts": {
    "dev": "rs dev",
    "build": "rs build",
    "preview": "rs preview",
    "test": "rs test",
    "lint": "rs lint",
    "format": "rs fmt"
  }
}
```

package scripts 会使用项目本地安装的 `rs` 命令，因此无需全局安装 Rstack。

Rstack 提供以下命令：

- [`rs dev`](/zh/guide/cli/dev.md)：启动应用开发服务器。
- [`rs build`](/zh/guide/cli/build.md)：构建应用的生产版本。
- [`rs preview`](/zh/guide/cli/preview.md)：在本地预览应用的生产构建产物。
- [`rs lib`](/zh/guide/cli/lib.md)：使用 Rslib 构建库。
- [`rs doc`](/zh/guide/cli/doc.md)：使用 Rspress 开发、构建或预览文档站点。
- [`rs test`](/zh/guide/cli/test.md)：使用 Rstest 运行测试。
- [`rs lint`](/zh/guide/cli/lint.md)：使用 Rslint 检查源代码。
- [`rs fmt`](/zh/guide/cli/fmt.md)：格式化代码。
- [`rs setup`](/zh/guide/cli/setup.md)：安装仓库级 Git hooks。
- [`rs staged`](/zh/guide/cli/staged.md)：使用 lint-staged 对 Git 暂存区中的文件运行任务。

## 配置 Rstack \{#configure-rstack}

在项目根目录创建 `rstack.config.ts`，并注册项目所需的配置。以下是一个包含应用、测试和代码检查的最小示例：

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

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

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

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

所有可用的配置 API 请参见[配置](/zh/guide/configuration.md)。

## AI

如需了解如何配合 Coding Agent 使用 Rstack CLI，请参阅 [AI 指南](/zh/guide/ai.md)。



---
url: /zh/guide/configuration.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/configuration.md.

# 配置 \{#configuration}

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

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

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

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

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

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

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

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

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

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

- `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}

每次执行 `rs` 命令时，Rstack 都会加载并执行配置文件，然后只解析当前命令需要的配置函数。

如果配置需要导入插件或其他工具专属依赖，请使用异步配置函数，并在函数内通过动态 `import()` 加载这些依赖。这样只有解析该配置时才会加载相关依赖。

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

define.app(async () => {
  const { pluginReact } = await import('@rsbuild/plugin-react');

  return {
    plugins: [pluginReact()],
  };
});
```

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

各 API 沿用底层工具的配置格式。使用 Rstack 已重导出的 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 的可选依赖。每个使用 `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 会通过 Rsbuild 适配器让测试配置自动继承 `define.app()`；如果未定义应用配置，则通过 Rslib 适配器回退到 `define.lib()`。二者同时存在时，应用配置的优先级更高。显式设置 `extends` 可关闭自动继承。

如果测试根配置未定义 `extends` 且包含 `projects`，Rstack 会为每个未自行设置 `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(async () => {
  const { js, ts } = await import('rstack/lint');

  return [js.configs.recommended, ts.configs.recommended];
});
```

### `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()`；缺少配置时会报错。



---
url: /zh/guide/ai.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/ai.md.

# AI

为了帮助 Coding Agent 理解 Rstack CLI 的命令、配置和最佳实践，Rstack CLI 提供了以下资源：

- [AGENTS.md](#agentsmd)
- [Agent Skills](#agent-skills)
- [llms.txt](#llmstxt)
- [Markdown 文档](#markdown-docs)

## AGENTS.md

使用 [create-rstack](https://www.npmjs.com/package/create-rstack) 创建的项目会包含一个遵循 [`AGENTS.md`](https://agents.md/) 规范的文件，为 Coding Agent 提供使用 Rstack CLI 所需的关键上下文。

你也可以将以下内容复制到自己的 `AGENTS.md` 中：

```markdown wrapCode title="AGENTS.md"
This project uses Rstack CLI as its JavaScript toolchain.

- Before working with `rs` commands, `rstack.config.*` files, or imports from `rstack`, start with `node_modules/rstack/docs/llms.txt`, then read only the linked pages relevant to the task.
- For command details, use `rs -h` or `rs <command> -h`.
- If the local documentation is unavailable, use https://rstack.rs/llms.txt and `rs <command> -h`.
```

这段内容与 [rstack-cli-best-practices](#rstack-cli-best-practices) Skill 作用相似，都能指导 Coding Agent 使用 Rstack CLI 并查找相关文档。将其添加到 `AGENTS.md` 或安装该 Skill，任选其一即可。

## Agent Skills

Rstack CLI 提供面向特定领域的 Agent Skills，帮助 Coding Agent 更准确地提供建议并执行相关任务。

### rstack-cli-best-practices

[rstack-cli-best-practices](https://github.com/rstackjs/rstack-cli/tree/main/.agents/skills/rstack-cli-best-practices) Skill 提供 Rstack CLI 的使用指南和最佳实践。

使用 [skills](https://www.npmjs.com/package/skills) 包安装该 Skill：


```sh [npx]
npx skills add rstackjs/rstack-cli --skill rstack-cli-best-practices
```

```sh [yarn]
yarn dlx skills add rstackjs/rstack-cli --skill rstack-cli-best-practices
```

```sh [pnpm]
pnpm dlx skills add rstackjs/rstack-cli --skill rstack-cli-best-practices
```

```sh [bunx]
bunx skills add rstackjs/rstack-cli --skill rstack-cli-best-practices
```

```sh [deno]
deno run -A npm:skills add rstackjs/rstack-cli --skill rstack-cli-best-practices
```

### migrate-to-rstack-cli

[migrate-to-rstack-cli](https://github.com/rstackjs/rstack-cli/tree/main/.agents/skills/migrate-to-rstack-cli) Skill 可以将使用独立 Rstack 工具及相关开发工具的项目迁移到 Rstack CLI。

迁移现有项目时，安装该 Skill：


```sh [npx]
npx skills add rstackjs/rstack-cli --skill migrate-to-rstack-cli
```

```sh [yarn]
yarn dlx skills add rstackjs/rstack-cli --skill migrate-to-rstack-cli
```

```sh [pnpm]
pnpm dlx skills add rstackjs/rstack-cli --skill migrate-to-rstack-cli
```

```sh [bunx]
bunx skills add rstackjs/rstack-cli --skill migrate-to-rstack-cli
```

```sh [deno]
deno run -A npm:skills add rstackjs/rstack-cli --skill migrate-to-rstack-cli
```

支持的工具和迁移说明请参阅[迁移到 Rstack CLI](/zh/guide/migration.md)。

## llms.txt

[llms.txt](https://llmstxt.org/) 是一种帮助 LLM 发现和使用项目文档的标准规范。Rstack CLI 文档站提供了以下文件：

- [llms.txt](https://rstack.rs/zh/llms.txt)：结构化索引文件，包含每篇文档的标题、链接和描述。

```text
https://rstack.rs/zh/llms.txt
```

- [llms-full.txt](https://rstack.rs/zh/llms-full.txt)：包含所有文档完整内容的单个文件。

```text
https://rstack.rs/zh/llms-full.txt
```

当 Agent 可以按需跟随链接并只加载与任务相关的页面时，使用 `llms.txt`。当 Agent 需要在同一上下文中读取完整文档，并且可以接受更多 token 消耗时，使用 `llms-full.txt`。

## Markdown 文档 \{#markdown-docs}

Rstack CLI 的每篇文档都有对应的 `.md` 纯文本版本，可以直接提供给 Agent。在任意文档页面的标题下方使用「复制 Markdown」或「复制 Markdown 链接」，即可复制文档内容或 URL。

```text
https://rstack.rs/zh/guide/quick-start.md
```



---
url: /zh/guide/api-reference.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/api-reference.md.

# API 参考 \{#api-reference}

Rstack 提供统一的配置 API，并通过专用子路径重导出 Rsbuild、Rslib、Rstest 和 Rslint 的公开 API。建议优先从这些子路径导入，以统一依赖入口，并确保 API 与 Rstack 集成的工具版本保持一致。

## 导入路径 \{#import-paths}

| 导入路径                     | 内容                                     | 使用场景            |
| ------------------------ | -------------------------------------- | --------------- |
| `rstack`                 | Rstack 配置 API                          | 注册各项工具配置        |
| `rstack/app`             | `@rsbuild/core` 的公开 API                | 构建应用及扩展 Rsbuild |
| `rstack/lib`             | `@rslib/core` 的公开 API                  | 构建库及扩展 Rslib    |
| `rstack/test`            | `@rstest/core` 的公开 API                 | 编写测试及配置测试项目     |
| `rstack/lint`            | `@rslint/core` 的公开 API                 | 使用 Rslint 预设和插件 |
| `rstack/types`           | Rsbuild 与 Rslib 共用的项目类型                | 为应用和库的源码提供类型    |
| `rstack/test/globals`    | Rstest 全局 API 声明                       | 启用全局测试 API 类型   |
| `rstack/test/importMeta` | `import.meta.rstest` 的 `ImportMeta` 声明 | 为源码内测试提供类型      |

## 主入口 \{#main-entry-point}

### `define`

从 `rstack` 导入 `define`，用于在 `rstack.config.ts` 中注册各项工具配置；详细用法请参阅[配置 API](/zh/guide/configuration.md#configuration-apis)。

## 重导出 \{#re-exports}

以下工具子路径均会重导出对应 core 包的公开 API。通过这些 Rstack 入口导入，可以让依赖入口和工具版本与 Rstack 集成的工具链保持一致。

### `rstack/app`

`rstack/app` 重导出 `@rsbuild/core` 的全部公开 API，包括用于创建和控制 Rsbuild 实例的 API。

```ts
import { createRsbuild, mergeRsbuildConfig } from 'rstack/app';
```

具体用法请参阅 [Rsbuild 核心 API](https://rsbuild.rs/zh/api/javascript-api/core)。

### `rstack/lib`

`rstack/lib` 重导出 `@rslib/core` 的全部公开 API，包括用于创建 Rslib 实例和合并 Rslib 配置的 API。

```ts
import { createRslib, mergeRslibConfig } from 'rstack/lib';
```

具体用法请参阅 [Rslib 核心 API](https://rslib.rs/zh/api/javascript-api/core)。

### `rstack/test`

`rstack/test` 重导出 `@rstest/core` 的全部公开 API，包括用于定义测试、编写断言、模拟模块和合并测试配置的 API。

```ts
import { describe, expect, test } from 'rstack/test';
```

测试 API 请参阅 [Rstest 运行时 API](https://rstest.rs/zh/api/runtime-api/)，配置辅助 API 请参阅 [Rstest 核心 API](https://rstest.rs/zh/api/javascript-api/rstest-core)。

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

### `rstack/lint`

`rstack/lint` 重导出 `@rslint/core` 的全部公开 API，包括 JavaScript 和 TypeScript 预设以及框架插件。

```ts
import { js, reactPlugin, ts } from 'rstack/lint';
```

可用的预设和插件请参阅 [Rslint 规则和预设](https://rslint.rs/config/rules-and-presets)。

## TypeScript 类型 \{#typescript-types}

以下纯类型入口用于为 TypeScript 项目补充环境类型声明。请仅将项目需要的入口添加到 `tsconfig.json` 的 [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) 中。

### `rstack/types`

`rstack/types` 提供 Rsbuild 与 Rslib 共用的项目级类型声明，包括 `import.meta.env` 和静态资源导入的类型。请使用该入口替代 `@rsbuild/core/types` 或 `@rslib/core/types`。

```json title="tsconfig.json"
{
  "compilerOptions": {
    "types": ["rstack/types", "node"]
  }
}
```

### `rstack/test/globals`

`rstack/test/globals` 提供 `test`、`expect` 和生命周期钩子等 Rstest API 的全局声明。启用 Rstest 的 [`globals`](https://rstest.rs/zh/config/test/globals) 选项且测试代码不显式导入这些 API 时，请添加该入口。

```json title="tsconfig.json"
{
  "compilerOptions": {
    "types": ["rstack/test/globals", "node"]
  }
}
```

### `rstack/test/importMeta`

`rstack/test/importMeta` 为 `ImportMeta` 增加可选的 `rstest` 属性，为源码内测试中的 `import.meta.rstest` 提供类型支持。

```json title="tsconfig.json"
{
  "compilerOptions": {
    "types": ["rstack/test/importMeta", "node"]
  }
}
```



---
url: /zh/guide/migration.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/migration.md.

# 迁移到 Rstack CLI \{#migrate-to-rstack-cli}

迁移现有项目时，推荐使用 `migrate-to-rstack-cli` Skill。该 Skill 会分析项目，并自动将仓库中使用的 Rstack 工具及 Prettier、Husky 等受支持工具迁移到 Rstack CLI。

## 使用迁移 Skill \{#use-the-migration-skill}

首先安装该 Skill：

```bash
npx skills add rstackjs/rstack-cli --skill migrate-to-rstack-cli
```

安装完成后，向 Coding Agent 发送以下 Prompt：

```text
使用 migrate-to-rstack-cli Skill 将当前项目迁移到 Rstack CLI。
```

## 支持的工具 \{#supported-tools}

该 Skill 可以直接迁移以下独立工具：

- **Rstack 工具链：**[Rsbuild](https://rsbuild.rs/zh/)、[Rslib](https://rslib.rs/zh/)、[Rstest](https://rstest.rs/zh/)、[Rslint](https://rslint.rs/) 和 [Rspress](https://rspress.rs/zh/)
- **代码格式化：**[Prettier](https://github.com/prettier/prettier)
- **暂存文件处理：**[lint-staged](https://github.com/lint-staged/lint-staged) 和 [nano-staged](https://github.com/usmanyunusov/nano-staged)
- **Git hooks：**[Husky](https://github.com/typicode/husky) 和 [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks)

## 不支持的工具 \{#unsupported-tools}

该 Skill 不会直接迁移上面列表之外的工具。如果项目使用以下工具，请先将其迁移到对应的 Rstack 工具，再运行 `migrate-to-rstack-cli` Skill：

- **应用构建：**&#x53C2;考 Rsbuild 的 [webpack 迁移指南](https://rsbuild.rs/zh/guide/migration/webpack)、[Vite 迁移指南](https://rsbuild.rs/zh/guide/migration/vite)、[Create React App 迁移指南](https://rsbuild.rs/zh/guide/migration/cra) 或 [Vue CLI 迁移指南](https://rsbuild.rs/zh/guide/migration/vue-cli)，将项目迁移到 Rsbuild。
- **库构建：**&#x53C2;考 Rslib 的 [tsup 迁移指南](https://rslib.rs/zh/guide/migration/tsup) 或 [tsc 迁移指南](https://rslib.rs/zh/guide/migration/tsc)，将库迁移到 Rslib。
- **测试：**&#x53C2;考 Rstest 的 [Jest 迁移指南](https://rstest.rs/zh/guide/migration/jest) 或 [Vitest 迁移指南](https://rstest.rs/zh/guide/migration/vitest)，将项目迁移到 Rstest。
- **代码检查：**&#x53C2;考 [Rslint 入门指南](https://rslint.rs/guide/)，将 ESLint 或其他代码检查工具迁移到 Rslint。



---
url: /zh/guide/testing.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/testing.md.

# 测试 \{#testing}

Rstack 使用 [Rstest](https://rstest.rs/zh/) 运行测试。

```bash
rs test
```

命令行选项和子命令请参阅 [`rs test`](/zh/guide/cli/test.md)。

## 配置测试 \{#configure-tests}

通过 [`define.test()`](/zh/guide/configuration.md#define-test) 注册 Rstest 配置，其用法与将配置传给 Rstest 的 `defineConfig()` 一致：

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

define.test({
  testEnvironment: 'node',
});
```

## 测试 API \{#test-apis}

测试 API 和配置辅助函数可从 [`rstack/test`](/zh/guide/api-reference.md#rstacktest) 导入：

```ts
import { defineInlineProject, expect, test } from 'rstack/test';
```

## 单项目 \{#single-project}

对于单个测试项目，直接将 Rstest 选项传给 `define.test()`：

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

define.app({
  // 共享的应用配置
});

define.test({
  testEnvironment: 'happy-dom',
});
```

未设置 `extends` 时，Rstack 会通过 Rsbuild 适配器让测试配置继承 `define.app()`。如果没有应用配置，则通过 Rslib 适配器回退到 `define.lib()`。同时定义两者时，`define.app()` 的优先级更高。

## 多项目 \{#multiple-projects}

通过 Rstest 的 [`projects`](https://rstest.rs/zh/config/test/projects) 选项可以同时运行多套测试配置。每一项既可以是内联项目，也可以是由 Rstest 解析为外部项目的字符串。

### 内联项目 \{#inline-projects}

不同测试环境需要共享当前应用或库配置时，请使用内联项目：

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

define.app({
  // 由两个内联项目共享
});

define.test({
  projects: [
    defineInlineProject({
      name: 'node',
      include: ['./tests/node/**/*.test.ts'],
      testEnvironment: 'node',
    }),
    defineInlineProject({
      name: 'dom',
      include: ['./tests/dom/**/*.test.tsx'],
      testEnvironment: 'happy-dom',
    }),
  ],
});
```

Rstack 会将对应的适配器应用到每个未设置 `extends` 的内联项目。函数形式的 `define.app()` 或 `define.lib()` 配置只会解析一次，再由这些内联项目共享。

按项目名称运行单个项目：

```bash
rs test --project dom
```

完整的 React SSR 示例请参阅 [`examples/rstest-inline-projects`](https://github.com/rstackjs/rstack-cli/tree/main/examples/rstest-inline-projects)，该示例使用 Node.js 和 happy-dom 两种测试环境。

### 外部项目 \{#external-projects}

使用字符串形式的配置项加载外部项目：

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

define.test({
  projects: ['./legacy/rstest.config.ts'],
});
```

Rstack 会将字符串形式的项目原样传给 Rstest。外部项目会加载自己的配置，不会继承当前的 `define.app()` 或 `define.lib()` 配置。每个项目需要独立管理配置时，请使用外部项目。

## 自定义继承 \{#customize-inheritance}

项目不应继承当前应用或库配置时，请显式设置 Rstest 的 [`extends`](https://rstest.rs/zh/config/test/extends) 选项：

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

define.test({
  projects: [
    defineInlineProject({
      name: 'standalone',
      extends: {
        testEnvironment: 'node',
      },
    }),
  ],
});
```

在内联项目中设置 `extends`，只会关闭当前项目的自动继承。在 `define.test()` 的根配置中设置该选项，则会关闭整个测试配置的自动继承。



---
url: /zh/guide/formatting.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/formatting.md.

# 格式化 \{#formatting}

Rstack CLI 提供了基于 [Prettier](https://prettier.io/) 的格式化工具。相比直接使用 Prettier，`rs fmt` 的性能更好，主要得益于以下两点：

- **并行格式化**：通过 worker 池并行格式化文件。
- **Yuku 解析器**：默认使用高性能的 [Yuku](https://yuku.fyi/) 解析器处理 JavaScript、JSX 和 TypeScript 文件。
- **持久化缓存**：基于文件内容缓存结果，后续运行可以跳过未变化文件的格式化。

`rs fmt` 兼容 Prettier 的选项和插件，并提供更多内置能力，例如支持[排序 package.json 字段](#sort-package-json)。

## 基本用法 \{#basic-usage}

直接运行 `rs fmt`，即可格式化当前目录中的文件并保存修改：

```bash
rs fmt
```

使用 `--check` 检查文件是否已格式化，而不修改文件：

```bash
rs fmt --check
```

更多命令行选项请参考 [`rs fmt` CLI 文档](/zh/guide/cli/fmt.md)。

## 配置 \{#configuration}

在 `rstack.config.ts` 中使用 [`define.fmt()`](/zh/guide/configuration.md#define-fmt) 设置格式化规则。它支持所有的 [Prettier 选项](https://prettier.io/docs/options)：

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

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

除了 Prettier 选项和 `overrides`，Rstack 还提供两个选项：

- [`ignorePatterns`](#ignore-files)：使用兼容 Gitignore 的模式排除文件。
- [`sortPackageJson`](#sort-package-json)：对 `package.json` 中的字段排序，默认值为 `false`。

:::warning Prettier 配置文件

`rs fmt` 不会自动加载 Prettier 配置文件、`.prettierignore` 或 `.editorconfig`。请在 `define.fmt()` 中设置格式化选项和额外的忽略规则。如需显式加载 ignore 文件，请使用 [`--ignore-path`](/zh/guide/cli/fmt.md#--ignore-path-path)。

:::

## 格式化范围 \{#formatting-scope}

`rs fmt` 根据命令行中传入的路径确定格式化范围。以下输入可以组合使用：

- **文件**：只格式化指定文件。
- **目录**：递归扫描目录并格式化支持的文件。
- **glob 模式**：匹配多个路径，并通过以 `!` 开头的模式排除匹配结果。

不传入路径时，`rs fmt` 默认格式化当前目录。所有 glob 模式都基于当前工作目录解析。请为 glob 添加引号，避免它们被 shell 提前展开：

```bash
# 格式化一个目录和一个文件
rs fmt src package.json

# 格式化 JavaScript 和 TypeScript 文件，并排除生成文件
rs fmt "src/**/*.{js,ts}" "!src/generated/**"
```

扫描目录或 glob 时，`rs fmt` 会遵循 `.gitignore` 规则、跳过二进制文件，并且不会遍历版本控制目录或 `node_modules`。Prettier 无法推断解析器的文件也会被跳过。

`.gitignore` 只在扫描目录和 glob 时生效，不会排除命令行中显式传入的文件。如果需要始终排除某个文件，请使用 [`ignorePatterns`](#ignore-files)。

## 忽略文件 \{#ignore-files}

使用 `ignorePatterns` 排除不需要格式化的文件：

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

define.fmt({
  ignorePatterns: ['dist/**', 'coverage/**', '**/generated/**'],
});
```

这些模式遵循 Gitignore 语法，并且基于 Rstack 配置文件所在的目录解析。由于规则会在确定格式化范围后生效，因此也会排除命令行中显式传入的文件。

### Lock 文件 \{#lock-files}

`rs fmt` 默认忽略常见的 lock 文件，包括 `package-lock.json` 和 `pnpm-lock.yaml`。

如果你需要格式化这些文件，可以使用否定模式主动包含它们：

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

define.fmt({
  ignorePatterns: ['!pnpm-lock.yaml'],
});
```

### 忽略顺序 \{#ignore-order}

`rs fmt` 会通过以下三个步骤，决定需要格式化哪些路径：

1. **处理命令行参数和 `.gitignore`**：首先处理命令行中指定的文件、目录和 glob 模式。以 `!` 开头的 glob 模式用于排除路径。扫描目录或 glob 模式时会遵循 `.gitignore`，直接指定的文件则不会。在这一步被排除的路径无法被后续规则重新包含。
2. **应用默认忽略规则和 `ignorePatterns`**：默认忽略 [lock 文件](#lock-files)，随后应用 `ignorePatterns`。这些规则按顺序匹配，后面的规则优先。例如，`!pnpm-lock.yaml` 可以重新包含默认忽略的文件。
3. **应用 [`--ignore-path`](/zh/guide/cli/fmt.md#--ignore-path-path) 指定的文件**：每个 ignore 文件单独匹配，同一文件中后面的规则优先。不同 ignore 文件与 `ignorePatterns` 的排除结果会叠加：只要任一来源忽略某个路径，该路径就会保持排除，即使其他来源尝试重新包含它。

> 即使命令行直接指定了某个文件，默认忽略规则、`ignorePatterns` 和 `--ignore-path` 中的规则仍然有效。通过 [`--stdin-filepath`](/zh/guide/cli/fmt.md#--stdin-filepath-path) 指定的路径也是如此。

## 排序 package.json 字段 \{#sort-package-json}

启用 `sortPackageJson` 后，`rs fmt` 会使用 [`sort-package-json`](https://github.com/keithamus/sort-package-json) 对每个待格式化的 `package.json` 中的字段排序：

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

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

## 覆盖配置 \{#overrides}

通过 `overrides` 字段，可以为特定文件单独设置格式化选项。每一项都支持以下字段：

- `files`：需要应用格式化选项的文件或 glob 模式。
- `options`：应用于匹配文件的格式化选项。
- `excludeFiles`：可选，需要从匹配结果中排除的文件或 glob 模式。

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

define.fmt({
  overrides: [
    {
      files: 'docs/**/*.md',
      excludeFiles: 'docs/generated/**',
      options: {
        proseWrap: 'always',
      },
    },
  ],
});
```

### 模式匹配 \{#pattern-matching}

`files` 和 `excludeFiles` 模式都基于 Rstack 配置文件所在目录解析。

在 `files` 中，不包含 `/` 的模式会匹配任意深度的文件名，包含 `/` 的模式则匹配相对路径。下面示例中的 `*.md` 会匹配任意目录中的 Markdown 文件，而 `scripts/**/*.js` 会匹配相对于 Rstack 配置文件所在目录的路径：

```ts
define.fmt({
  overrides: [
    { files: '*.md', options: { proseWrap: 'always' } },
    { files: 'scripts/**/*.js', options: { singleQuote: true } },
  ],
});
```

### 合并顺序 \{#merge-order}

如果同一文件匹配多条 override 规则，Rstack 会按声明顺序合并配置，后面的值优先。下面的 `README.md` 会同时匹配两条规则，因此最终的 `printWidth` 为 `80`：

```ts
define.fmt({
  overrides: [
    { files: '*.md', options: { printWidth: 100 } },
    { files: 'README.md', options: { printWidth: 80 } },
  ],
});
```

## 缓存 \{#cache}

`rs fmt` 默认会在基于文件的 `--write`、`--check` 和 `--list-different` 调用中使用持久化缓存。格式化结果基于文件内容和最终格式化选项；任意一项发生变化时，文件都会重新格式化。不支持的 parser 查询结果通常基于文件路径和最终选项。对于没有扩展名的文件，还会基于文件内容，因为 Prettier 可能从 shebang 推断 parser。已安装的 Prettier 插件通过包名、版本和入口进行识别；本地插件、链接插件或缺少版本信息的插件会绕过缓存。

默认缓存目录位于 Rstack 配置根目录下的 `.rstack/cache/fmt`。从子目录运行命令时，仍会使用解析到的 `rstack.config.*` 文件旁的缓存。stdin 格式化不会使用该缓存。

使用 [`--cache-location <path>`](/zh/guide/cli/fmt.md#--cache-location-path) 可以将缓存保存到其他目录。相对路径基于当前工作目录解析。自定义目录会从文件发现中排除，但不会被 Git 自动忽略。

使用 [`--no-cache`](/zh/guide/cli/fmt.md#--no-cache) 可以在运行时跳过缓存读取、创建和更新：

```bash
rs fmt --no-cache
```

可以安全删除 `.rstack/cache` 来清理缓存结果。不要将整个 `.rstack` 目录视为可随意删除的内容，因为其中还可能包含用户维护的 Git hook 脚本。

## Prettier 插件 \{#prettier-plugins}

如果需要使用 Rstack 未内置的格式化能力，可以安装相应的 [Prettier 插件](https://prettier.io/docs/plugins)，并添加到 `plugins` 中。插件支持通过包名、文件路径或 URL 引用，其中包名和相对路径基于 Rstack 配置文件所在的目录解析。

由于 `rs fmt` 会在 worker 中加载插件，因此不支持直接传入插件对象。请通过包名、路径或 URL 引用插件。例如，安装并启用 [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)：


```sh [npm]
npm install -D prettier-plugin-tailwindcss
```

```sh [yarn]
yarn add -D prettier-plugin-tailwindcss
```

```sh [pnpm]
pnpm add -D prettier-plugin-tailwindcss
```

```sh [bun]
bun add -D prettier-plugin-tailwindcss
```

```sh [deno]
deno add -D npm:prettier-plugin-tailwindcss
```

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

define.fmt({
  plugins: ['prettier-plugin-tailwindcss'],
});
```

如果只需要为特定文件启用插件，可以在 [`overrides`](#overrides) 的 `options` 中配置 `plugins`。



---
url: /zh/guide/monorepo.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/monorepo.md.

# Monorepo

本指南介绍如何在 Monorepo 中使用 Rstack CLI，以及如何让它与 [Turborepo](https://turborepo.com/docs)、[Nx](https://nx.dev/docs/getting-started/intro) 等任务编排工具协同工作。

主要内容包括管理 Rstack 依赖、在根目录统一配置代码检查、格式化和暂存文件任务，以及为 Web 应用和库项目定义独立配置。

## 目录结构 \{#project-structure}

推荐使用两层配置：

- 根目录统一管理 Rstack 版本、lint 和格式化规则，以及暂存文件任务。
- 每个应用或库使用自己的 [Rstack 配置](/zh/guide/configuration.md)，定义构建、测试或文档配置。

```text
.
├── package.json
├── rstack.config.ts
├── apps/
│   └── web/
│       ├── package.json
│       └── rstack.config.ts
└── packages/
    └── utils/
        ├── package.json
        └── rstack.config.ts
```

这种结构既能统一 Rstack 版本，也能让构建和测试配置靠近实际使用它们的项目。

## Rstack 依赖管理 \{#rstack-dependency-management}

在根目录的 `package.json` 中声明 Rstack，让各个项目默认使用同一个版本。安装方法请参考[快速上手](/zh/guide/quick-start.md#install-rstack)。

如果子项目需要使用与根目录不同版本的 `rstack`，可以在该项目中单独声明对应版本的 `rstack` 依赖。

Rsbuild 插件、测试库等项目专属依赖，建议定义在实际使用它们的子项目中。

## 根配置 \{#root-configuration}

在根目录的 `rstack.config.ts` 中使用 [`define.lint()`](/zh/guide/configuration.md#define-lint)、[`define.fmt()`](/zh/guide/configuration.md#define-fmt) 和 [`define.staged()`](/zh/guide/configuration.md#define-staged)，配置适用于整个仓库的检查和格式化：

```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.fmt({
  singleQuote: true,
  ignorePatterns: ['**/dist/**'],
});

define.staged({
  '*.{js,jsx,ts,tsx,mjs,cjs}': ['rs lint', 'rs fmt'],
  '*.{json,md,mdx,css,html,yml,yaml}': 'rs fmt',
});
```

在根目录的 `package.json` 中提供对应脚本：

```json title="package.json"
{
  "private": true,
  "scripts": {
    "lint": "rs lint",
    "format": "rs fmt",
    "check:format": "rs fmt --check",
    "staged": "rs staged"
  }
}
```

除非根目录本身也是一个需要构建的项目，否则不需要在根配置中添加应用或库的构建配置。

### 项目级 lint 规则 \{#project-specific-lint-rules}

如果部分项目需要不同的 lint 规则，可以通过 [`files`](https://rslint.rs/config/#files) 匹配对应文件。这里的路径从仓库根目录开始计算：

```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,
    {
      files: ['apps/web/**/*.{ts,tsx}'],
      rules: {
        '@typescript-eslint/no-explicit-any': 'off',
      },
    },
  ];
});
```

## 子项目配置 \{#project-configuration}

为每个使用 [Rstack 命令](/zh/guide/quick-start.md#cli-commands)的子项目创建 [`rstack.config.ts`](/zh/guide/configuration.md#configuration-file)，并且只配置该项目需要的功能。

Rstack 会加载当前工作目录中的配置，不会将子项目配置与根配置自动合并。

### Web 应用 \{#web-application}

Web 应用通常需要应用构建配置和可选的测试配置：

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

define.app(async () => {
  const { pluginReact } = await import('@rsbuild/plugin-react');

  return {
    plugins: [pluginReact()],
  };
});

define.test({
  globals: true,
});
```

在应用的 `package.json` 中添加脚本，例如：

```json title="apps/web/package.json"
{
  "name": "@example/web",
  "scripts": {
    "dev": "rs dev",
    "build": "rs build",
    "preview": "rs preview",
    "test": "rs test"
  }
}
```

### 库项目 \{#library-project}

库可以在一份配置中定义构建、测试和文档：

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

define.lib({
  dts: true,
  format: 'esm',
});

define.test({
  testEnvironment: 'node',
});

// 仅当库需要文档站点时配置。
define.doc({
  root: 'docs',
  title: 'Utils',
});
```

在库的 `package.json` 中添加脚本，例如：

```json title="packages/utils/package.json"
{
  "name": "@example/utils",
  "scripts": {
    "build": "rs lib",
    "dev": "rs lib -w",
    "test": "rs test",
    "doc": "rs doc"
  }
}
```



---
url: /zh/guide/cli/dev.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/dev.md.

# dev

`rs dev` 命令用于启动应用的 [Rsbuild 开发服务器](https://rsbuild.rs/zh/guide/basic/server)。它会以开发模式编译源码、监听文件变化，并按需进行模块热更新（HMR）或刷新页面。

## 用法 \{#usage}

```bash
rs dev [options]
```

该命令会加载通过 [`define.app()`](/zh/guide/configuration.md#define-app) 注册的应用配置。

## 选项 \{#options}

`rs dev` 支持与 Rsbuild 相同的开发服务器选项，具体说明请参见 [Rsbuild CLI 文档](https://rsbuild.rs/zh/guide/basic/cli#rsbuild)。

示例：

```bash
# 启动服务器并在浏览器中打开页面
rs dev --open

# 使用 8080 端口，并在端口已被占用时退出
rs dev --port 8080 --strict-port

# 允许通过局域网访问开发服务器
rs dev --host
```

## 配置 \{#configuration}

在 [Rstack 配置文件](/zh/guide/configuration.md#configuration-file)中通过 [`define.app()`](/zh/guide/configuration.md#define-app) 配置开发服务器。该 API 支持标准的 [Rsbuild 配置](https://rsbuild.rs/zh/config/)：

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

define.app({
  server: {
    open: true,
    port: 8080,
  },
});
```



---
url: /zh/guide/cli/build.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/build.md.

# build

`rs build` 命令使用 [Rsbuild](https://rsbuild.rs/zh/guide/basic/cli#rsbuild-build) 构建应用的生产版本。

## 用法 \{#usage}

```bash
rs build [options]
```

该命令会加载通过 [`define.app()`](/zh/guide/configuration.md#define-app) 注册的应用配置。

## 选项 \{#options}

`rs build` 支持与 Rsbuild 相同的构建选项，具体说明请参见 [Rsbuild CLI 文档](https://rsbuild.rs/zh/guide/basic/cli#rsbuild-build)。

示例：

```bash
# 将构建产物写入 output 目录
rs build --dist-path output

# 为构建产物生成 source map
rs build --source-map

# 在文件变化时重新构建
rs build --watch
```

## 配置 \{#configuration}

在 [Rstack 配置文件](/zh/guide/configuration.md#configuration-file)中通过 [`define.app()`](/zh/guide/configuration.md#define-app) 配置生产构建。该 API 支持标准的 [Rsbuild 配置](https://rsbuild.rs/zh/config/)：

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

define.app({
  output: {
    distPath: {
      root: 'output',
    },
    sourceMap: true,
  },
});
```



---
url: /zh/guide/cli/preview.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/preview.md.

# preview

`rs preview` 命令使用 [Rsbuild](https://rsbuild.rs/zh/guide/basic/cli#rsbuild-preview) 在本地预览应用的生产构建。

## 用法 \{#usage}

```bash
rs preview [options]
```

该命令会加载通过 [`define.app()`](/zh/guide/configuration.md#define-app) 注册的应用配置。启动预览服务器前，请先运行 [`rs build`](/zh/guide/cli/build.md) 生成生产构建：

```bash
rs build
rs preview
```

`rs preview` 仅用于本地预览，请勿将其用作生产服务器。

## 选项 \{#options}

`rs preview` 支持与 Rsbuild 相同的预览服务器选项，具体说明请参见 [Rsbuild CLI 文档](https://rsbuild.rs/zh/guide/basic/cli#rsbuild-preview)。

示例：

```bash
# 启动预览服务器并在浏览器中打开页面
rs preview --open

# 使用 8080 端口，并在端口已被占用时退出
rs preview --port 8080 --strict-port

# 允许通过局域网访问预览服务器
rs preview --host
```

## 配置 \{#configuration}

在 [Rstack 配置文件](/zh/guide/configuration.md#configuration-file)中通过 [`define.app()`](/zh/guide/configuration.md#define-app) 配置预览服务器。该 API 支持标准的 [Rsbuild 配置](https://rsbuild.rs/zh/config/)：

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

define.app({
  server: {
    open: true,
    port: 8080,
  },
});
```



---
url: /zh/guide/cli/lib.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/lib.md.

# lib

`rs lib` 命令使用 [Rslib](https://rslib.rs/zh/guide/basic/cli#rslib) 构建库产物。

## 用法 \{#usage}

```bash
rs lib [command] [options]
```

该命令会加载通过 [`define.lib()`](/zh/guide/configuration.md#define-lib) 注册的库配置。未指定子命令时，默认执行库构建。

## 选项 \{#options}

`rs lib` 支持与 Rslib 相同的库构建选项，具体说明请参见 [Rslib CLI 文档](https://rslib.rs/zh/guide/basic/cli#rslib)。

示例：

```bash
# 构建产物并生成声明文件
rs lib --dts

# 在文件变化时重新构建
rs lib --watch
```

## 子命令 \{#subcommands}

### build

[`rs lib build`](https://rslib.rs/zh/guide/basic/cli#rslib) 用于构建生产环境的库产物，其效果与直接运行 `rs lib` 相同。

```bash
rs lib build
```

### inspect

[`rs lib inspect`](https://rslib.rs/zh/guide/basic/cli#rslib-inspect) 用于生成归一化后的 Rslib 配置及对应的 Rsbuild 和 Rspack 配置，以便检查最终生效的配置。

```bash
rs lib inspect
```

### mf-dev

[`rs lib mf-dev`](https://rslib.rs/zh/guide/basic/cli#rslib-mf-dev) 为使用模块联邦（`mf`）格式的库产物启动 Rsbuild 开发服务器，用于在宿主应用中开发和调试模块。

```bash
rs lib mf-dev
```

## 配置 \{#configuration}

在 [Rstack 配置文件](/zh/guide/configuration.md#configuration-file)中通过 [`define.lib()`](/zh/guide/configuration.md#define-lib) 配置库构建。该 API 支持标准的 [Rslib 配置](https://rslib.rs/zh/config/)：

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

define.lib({
  dts: true,
  format: 'esm',
});
```



---
url: /zh/guide/cli/doc.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/doc.md.

# doc

`rs doc` 命令使用 [Rspress](https://rspress.rs/zh/guide/start/introduction) 开发、构建和预览文档站点。

使用该命令前，请安装 [`@rspress/core`](https://www.npmjs.com/package/@rspress/core)：


```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
```

## 用法 \{#usage}

```bash
rs doc [command] [root] [options]
```

该命令会加载通过 [`define.doc()`](/zh/guide/configuration.md#define-doc) 注册的文档配置。未指定子命令时，默认启动 [Rspress 开发服务器](https://rspress.rs/zh/api/commands#rspress-dev)。可选的 `root` 参数用于覆盖配置中的文档根目录。

## 选项 \{#options}

`rs doc` 支持与对应 Rspress 命令相同的选项，具体说明请参见 [Rspress CLI 文档](https://rspress.rs/zh/api/commands)。

示例：

```bash
# 启动开发服务器
rs doc

# 使用自定义文档根目录
rs doc ./documentation

# 使用 8080 端口启动开发服务器
rs doc --port 8080
```

## 子命令 \{#subcommands}

### build

[`rs doc build`](https://rspress.rs/zh/api/commands#rspress-build) 用于构建生产环境的文档站点。

```bash
rs doc build
```

### preview

[`rs doc preview`](https://rspress.rs/zh/api/commands#rspress-preview) 用于在本地预览 `rs doc build` 生成的产物。

```bash
rs doc build
rs doc preview
```

### eject

[`rs doc eject`](https://rspress.rs/zh/api/commands#rspress-eject) 用于将 Rspress 内置主题组件复制到项目中进行自定义。不指定组件名称时，会列出所有可导出的组件。

```bash
rs doc eject
```

## 配置 \{#configuration}

在 [Rstack 配置文件](/zh/guide/configuration.md#configuration-file)中通过 [`define.doc()`](/zh/guide/configuration.md#define-doc) 配置文档站点。该 API 支持标准的 [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',
});
```



---
url: /zh/guide/cli/test.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/test.md.

# test

`rs test` 命令使用 [Rstest](https://rstest.rs/zh/guide/basic/cli) 运行测试。

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

## 用法 \{#usage}

```bash
rs test [command] [...filters] [options]
```

该命令会加载通过 [`define.test()`](/zh/guide/configuration.md#define-test) 注册的测试配置。

## 选项 \{#options}

`rs test` 支持与 Rstest 相同的测试运行选项和过滤方式，具体说明请参见 [Rstest CLI 文档](https://rstest.rs/zh/guide/basic/cli#cli-选项)和[过滤测试](https://rstest.rs/zh/guide/basic/test-filter)。

示例：

```bash
# 运行指定的测试文件
rs test tests/foo.test.ts

# 运行名称中包含 "login" 的测试
rs test -t login

# 收集代码覆盖率
rs test --coverage
```

## 子命令 \{#subcommands}

### run

[`rs test run`](https://rstest.rs/zh/guide/basic/cli#rstest-run) 用于在非监听模式下单次运行匹配的测试，适合 CI 环境。

```bash
rs test run
```

### watch

[`rs test watch`](https://rstest.rs/zh/guide/basic/cli#rstest-watch) 会在测试文件或其依赖发生变化时重新运行相关测试。

```bash
rs test watch
```

### list

[`rs test list`](https://rstest.rs/zh/guide/basic/cli#rstest-list) 用于列出匹配的测试，但不运行测试。

```bash
rs test list
```

### merge-reports

[`rs test merge-reports`](https://rstest.rs/zh/guide/basic/cli#rstest-merge-reports) 用于合并多个测试分片生成的 blob 报告。

```bash
rs test merge-reports
```

### init

[`rs test init`](https://rstest.rs/zh/guide/basic/cli#rstest-init) 用于为支持的项目类型初始化 Rstest 配置。

```bash
rs test init browser
```

## 配置 \{#configuration}

在 [Rstack 配置文件](/zh/guide/configuration.md#configuration-file)中通过 [`define.test()`](/zh/guide/configuration.md#define-test) 配置测试。该 API 支持标准的 [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',
});
```



---
url: /zh/guide/cli/lint.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/lint.md.

# lint

`rs lint` 命令使用 [Rslint](https://rslint.rs/guide/) 检查源代码。

## 用法 \{#usage}

```bash
rs lint [options] [files...]
```

该命令会加载通过 [`define.lint()`](/zh/guide/configuration.md#define-lint) 注册的代码检查配置。

## 选项 \{#options}

`rs lint` 支持与 Rslint 相同的命令行选项，具体说明请参见 [Rslint CLI 文档](https://rslint.rs/guide/cli)。

示例：

```bash
# 检查指定目录
rs lint src

# 自动修复问题
rs lint --fix

# 检查代码并运行 TypeScript 类型检查
rs lint --type-check
```

## 配置 \{#configuration}

在 [Rstack 配置文件](/zh/guide/configuration.md#configuration-file)中通过 [`define.lint()`](/zh/guide/configuration.md#define-lint) 配置代码检查。该 API 支持标准的 [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];
});
```



---
url: /zh/guide/cli/fmt.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/fmt.md.

# fmt

`rs fmt` 命令用于格式化文件或检查文件格式。详细用法请参考[格式化](/zh/guide/formatting.md)指南。

## 用法 \{#usage}

```bash
rs fmt [options] [files/globs...]
```

可以传入文件、目录或 glob 模式来指定格式化范围。不传入路径时，`rs fmt` 会格式化当前目录。路径解析和忽略规则请参考[格式化范围](/zh/guide/formatting.md#formatting-scope)。

示例：

```bash
# 格式化当前目录中的文件
rs fmt

# 格式化指定文件和目录
rs fmt src package.json

# 在 CI 中检查格式
rs fmt --check
```

`rs format` 是 `rs fmt` 的别名：

```bash
rs format
```

## 选项 \{#options}

### `--check`

检查文件是否已格式化，但不修改文件。输出会列出存在格式问题的文件，并提供便于阅读的汇总信息，因此适合在 CI 中使用：

```bash
rs fmt --check
```

`--check` 不能与 `--write` 或 `--list-different` 同时使用。

该命令使用以下退出状态码：

| 状态码 | 含义                |
| --- | ----------------- |
| `0` | 命令执行成功。           |
| `1` | 一个或多个文件存在格式问题。    |
| `2` | 命令无法运行或执行过程中遇到错误。 |

### `-h, --help`

显示命令用法和选项信息，但不格式化文件：

```bash
rs fmt --help
```

### `--ignore-path <path>`

使用 `--ignore-path` 从文件中加载额外的 Gitignore 兼容规则。

相对的 ignore 文件路径基于当前工作目录解析。文件中的规则基于该文件所在目录解析。

例如，在项目根目录执行以下命令：

```bash
rs fmt --ignore-path config/format.ignore
```

假设 `config/format.ignore` 包含以下规则：

```text title="config/format.ignore"
generated/**
```

这里，`config/format.ignore` 相对项目根目录定位。文件中的 `generated/**` 规则则相对 `config/` 目录解析。因此，它会忽略 `config/generated/**`，而不是项目根目录下的 `generated/**`。

加载的规则会作用于扫描得到的路径、显式传入的文件和 `--stdin-filepath`。

如需加载多个 ignore 文件，可以重复传入该选项：

```bash
rs fmt --ignore-path .prettierignore --ignore-path config/format.ignore
```

每个文件都是独立的忽略来源。关于这些来源与 `.gitignore`、默认忽略规则和 `ignorePatterns` 的组合方式，请参考[忽略顺序](/zh/guide/formatting.md#ignore-order)。

### `--ignore-unknown`

忽略无法推断 parser 的匹配文件。即使所有匹配文件的类型均未知，该选项也可以让命令成功退出：

```bash
rs fmt --ignore-unknown
```

短选项 `-u` 是 `--ignore-unknown` 的别名。

```bash
rs fmt -u
```

此选项不会忽略未匹配路径或 glob 的错误。如果集成需要同时容忍这两种情况，可以将它与 [`--no-error-on-unmatched-pattern`](#--no-error-on-unmatched-pattern) 一起使用。

与 `--stdin-filepath` 一起使用时，不支持的输入会被跳过，且不会输出内容。

### `--list-different`

输出未格式化文件的路径，但不提供 `--check` 的汇总信息。需要将结果交给其他命令处理时，可以使用此选项：

```bash
rs fmt --list-different
```

短选项 `-l` 是 `--list-different` 的别名：

```bash
rs fmt -l
```

此选项与 `--check` 使用相同的退出状态码，且不能与 `--write` 或 `--check` 同时使用。

### `--no-cache`

在当前调用中关闭持久化格式化缓存：

```bash
rs fmt --no-cache
```

默认情况下，`rs fmt` 会将缓存数据保存在 Rstack 配置根目录下的 `.rstack/cache/fmt` 中。`--no-cache` 会阻止命令读取、创建或更新该缓存。stdin 格式化始终不会使用持久化缓存。

缓存行为和清理方式请参考[缓存](/zh/guide/formatting.md#cache)。

### `--cache-location <path>`

将持久化缓存保存到自定义目录：

```bash
rs fmt --cache-location .cache/rs-fmt
```

相对路径基于当前工作目录解析，绝对路径则原样使用。目录会在需要时自动创建，并从文件发现中排除。与默认缓存位置不同，自定义目录不会自动生成 `.gitignore`；请将其排除在版本控制之外，或通过 CI 缓存配置进行管理。

同时使用两个选项时，优先使用 `--no-cache`，且不会从文件发现中排除自定义目录。

### `--no-error-on-unmatched-pattern`

如果传入的路径或 glob 没有匹配任何文件（包括所有匹配文件均被忽略的情况），则不输出诊断信息并成功退出：

```bash
rs fmt --no-error-on-unmatched-pattern 'src/**/*.ts'
```

例如，pre-commit 脚本可能会始终运行 `rs fmt`，即使暂存的改动中没有支持的文件。此选项可让命令在这种情况下成功退出，避免阻止提交。

> [`rs staged`](/zh/guide/cli/staged.md) 会为其中的 `rs fmt` 任务自动启用此行为。

### `--parallel-workers <count>`

将格式化 worker 的最大数量设置为正整数：

```bash
rs fmt --parallel-workers 4
```

省略此选项时，`rs fmt` 会根据可用的 CPU 并行度和匹配的文件数量，自动选择最多 8 个 worker。在资源受限的环境中，可以设置较小的值来限制 CPU 或内存用量。

### `--stdin-filepath <path>`

将 stdin 传入的内容按保存在 `<path>` 的文件进行格式化，例如用于编辑器集成。该路径用于确定 parser 和匹配的[覆盖配置](/zh/guide/formatting.md#overrides)，但不需要在磁盘上真实存在：

```bash
cat src/index.ts | rs fmt --stdin-filepath src/index.ts
```

格式化结果写入 stdout，诊断信息写入 stderr。若输入路径被忽略，`rs fmt` 会跳过格式化并原样输出内容；若无法根据路径推断 parser 或内容解析失败，则输出错误并以状态码 `2` 退出。

> `--stdin-filepath` 不能与文件参数或 `--write`、`--check`、`--list-different` 同时使用。

### `--with-node-modules`

处理 `node_modules` 中的文件。默认情况下，`rs fmt` 会排除这些文件：

```bash
rs fmt --with-node-modules node_modules/example/index.js
```

此选项只会关闭内置的 `node_modules` 排除规则。目录和 glob 扫描仍然遵循 `.gitignore`，`ignorePatterns` 和 `--ignore-path` 也会继续作用于所有输入。

### `--write`

将格式化结果写回文件。这是默认模式，因此可以省略 `--write`：

```bash
rs fmt src --write
```

短选项 `-w` 是 `--write` 的别名：

```bash
rs fmt -w src
```

`--write` 不能与 `--check` 或 `--list-different` 同时使用。



---
url: /zh/guide/cli/setup.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/setup.md.

# setup

`rs setup` 命令用于安装仓库级 [Git hooks](https://git-scm.com/docs/githooks)，并在调用该命令的项目中运行 hooks。

## 用法 \{#usage}

```bash
rs setup [options]
```

hook 脚本默认存放在 Git 仓库根目录下的 `.rstack/hooks`。如果当前目录不属于 Git 仓库，命令会跳过安装。

在负责管理仓库 hooks 的项目 `package.json` 中添加 `prepare` 脚本：

```json title="package.json"
{
  "scripts": {
    "prepare": "rs setup"
  }
}
```

执行一次该脚本，生成 hook 文件：


```sh [npm]
npm run prepare
```

```sh [yarn]
yarn run prepare
```

```sh [pnpm]
pnpm run prepare
```

```sh [bun]
bun run prepare
```

例如，创建一个 `pre-commit` hook，并在其中运行 [`rs staged`](/zh/guide/cli/staged.md)：

```sh title=".rstack/hooks/pre-commit"
rs staged
```

:::warning 已有 Git hook 管理工具

`rs setup` 会更新仓库的 [`core.hooksPath`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-corehooksPath)。检测到其他 hooks 路径或已有 Git hook 时，命令会跳过安装。请先迁移所需的 hooks 并移除已有 hooks 配置，再运行该命令。

:::

## 选项 \{#options}

### `--hooks-dir`

设置 hook 脚本的存放目录，路径相对于 Git 仓库根目录。

```bash
rs setup --hooks-dir config/git-hooks

# 路径包含空格时需要使用引号
rs setup --hooks-dir "config/git hooks"
```

使用自定义目录时，请将完整命令写入负责管理 hooks 的项目 `package.json`：

```json title="package.json"
{
  "scripts": {
    "prepare": "rs setup --hooks-dir config/git-hooks"
  }
}
```

> 为避免通过父目录路径在仓库之外创建或覆盖 Git hook 文件，路径中不能包含 `..`。

### `--help`

`--help`（或 `-h`）用于显示命令的用法和选项。

```bash
rs setup --help
```

## Hook 文件 \{#hook-files}

默认目录结构如下：

```text
.rstack/
└── hooks/
    ├── pre-commit        # 仓库 hook 脚本：编辑并提交
    └── _/                # 由 rs setup 生成；默认被 Git 忽略
        ├── .gitignore
        ├── .owner
        ├── runner
        ├── pre-commit
        ├── commit-msg
        └── ...
```

与 `_` 同级的文件是仓库 hook 脚本。`_` 目录包含生成文件，并由 Git 忽略。`rs setup` 会将 `core.hooksPath` 指向 `.rstack/hooks/_`；克隆仓库后或生成文件缺失时，请重新运行该命令。

## 支持的 hooks \{#supported-hooks}

Rstack 支持以下客户端 Git hooks：

- `pre-commit`
- `pre-merge-commit`
- `prepare-commit-msg`
- `commit-msg`
- `post-commit`
- `applypatch-msg`
- `pre-applypatch`
- `post-applypatch`
- `pre-rebase`
- `post-rewrite`
- `post-checkout`
- `post-merge`
- `pre-push`
- `pre-auto-gc`

在与 `_` 同级的位置创建对应的同名文件即可。

## Hook 运行时 \{#hook-runtime}

Rstack 使用 POSIX `sh -e` 运行 hook 脚本，并转发 Git 提供的参数和标准输入，同时返回 hook 的退出码。运行 hook 前，Rstack 会切换到安装 hooks 的项目，并将该项目的 `node_modules/.bin` 添加到 `PATH` 开头。

### 禁用与调试 \{#disable-and-debug}

将 `RSTACK_HOOKS` 设为 `0`，可以跳过安装或 hook 执行：

```bash
RSTACK_HOOKS=0 git commit -m "Skip hooks"
```

将 `RSTACK_HOOKS` 设为 `2`，可以跟踪 Rstack hook 运行时，包括调用 hook 脚本和处理退出码等步骤；如需跟踪 hook 脚本内部的命令，请在脚本中添加 `set -x`：

```bash
RSTACK_HOOKS=2 git commit -m "Trace hooks"
```

### 配置 hook 运行环境 \{#configure-the-hook-environment}

运行 hook 脚本前，Rstack 会加载以下可选的 POSIX shell 文件：

```text
${XDG_CONFIG_HOME:-$HOME/.config}/rstack/hooks-init.sh
```

可以在其中初始化 Node.js 版本管理器、更新 `PATH`，或为当前用户设置 `RSTACK_HOOKS=0`。

## Monorepo \{#monorepo}

在 monorepo 中，提供 Rstack 的项目可能位于 `frontend/` 等子目录。从该目录运行 `rs setup` 时，hooks 仍会安装到 Git 仓库根目录：

```text
repo/.rstack/hooks/
repo/.rstack/hooks/_/
core.hooksPath=.rstack/hooks/_
```

Rstack 会将 `frontend` 记录为负责管理 hooks 的项目。hook 脚本仍位于仓库根目录，但会从 `frontend` 目录运行，因此可以直接使用其中的配置和依赖，无需显式执行 `cd`：

```sh title=".rstack/hooks/pre-commit"
rs staged
```

一个 Git 仓库只能有一个 hooks owner。只有负责管理 hooks 的项目应在 `prepare` 脚本中调用 `rs setup`。其他项目调用时会收到警告并跳过。

如需更换 owner，请先从原项目的 `prepare` 脚本中移除 `rs setup`，删除生成的 `_` 目录，再从新项目运行 `rs setup`。

## 移除 hooks \{#remove-hooks}

如需移除由 Rstack 管理的 hooks：

1. 从 `prepare` 脚本中移除 `rs setup`。

2. 删除仓库的 hooks 路径配置：

   ```bash
   git config --local --unset core.hooksPath
   ```

3. 删除 `.rstack/hooks/` 或通过 `--hooks-dir` 指定的目录。

## 故障排查 \{#troubleshooting}

### Hook 未运行 \{#hook-does-not-run}

- 确认 hook 脚本使用[支持的名称](#supported-hooks)，并与 `_` 目录同级。
- 运行 `git config --local --get core.hooksPath`，检查配置的路径。
- 重新运行 `rs setup`，恢复生成文件及其可执行权限。
- 检查环境变量或初始化文件中是否设置了 `RSTACK_HOOKS=0`。
- 如果命令提示存在其他 hooks 配置，请先迁移或移除冲突配置，再重新运行该命令。
- 如果命令提示存在其他 Rstack owner，请按照 [Monorepo](#monorepo) 中的步骤转移 owner。

hook 脚本不需要可执行权限，因为 Rstack 会使用 `sh` 运行它。

### 找不到命令 \{#command-not-found}

退出码为 127 时，Rstack 会打印实际生效的 `PATH`。如果 GUI Git 客户端找不到 Node.js 或包管理器，请在 `hooks-init.sh` 中初始化相关环境。

### Windows 与 Yarn \{#windows-and-yarn}

在 Windows 上，hooks 会通过 [Git for Windows](https://gitforwindows.org/) 自带的 POSIX shell 运行。请在 hook 中使用 LF 换行符和 `/` 路径分隔符。

[Yarn PnP](https://yarnpkg.com/features/pnp) 不提供 `node_modules/.bin`。请通过 Yarn 脚本运行工具，例如 `yarn run test`；必要时可通过 `hooks-init.sh` 配置 Node.js 和 Yarn。



---
url: /zh/guide/cli/staged.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guide/cli/staged.md.

# staged

`rs staged` 命令使用 [lint-staged](https://github.com/lint-staged/lint-staged) 对 Git 暂存文件运行任务。

`rs staged` 可用于在提交代码前，对暂存文件运行 linter、格式化工具或其他检查。

常见做法是将 `rs staged` 与 [`rs setup`](/zh/guide/cli/setup.md) 配合使用，通过 `pre-commit` hook 运行暂存文件任务。

## 用法 \{#usage}

```bash
rs staged [options]
```

该命令会加载通过 [`define.staged()`](/zh/guide/configuration.md#define-staged) 注册的暂存文件任务。

## 选项 \{#options}

### `--allow-empty`

`--allow-empty` 允许在任务撤销全部暂存变更时创建空提交。

```bash
rs staged --allow-empty
```

### `--concurrent`

`--concurrent`（或 `-p`）用于设置并发运行的任务数量；设为 `false` 时串行运行。

```bash
rs staged --concurrent false
```

### `--cwd`

`--cwd` 用于设置运行所有任务时使用的工作目录。

```bash
rs staged --cwd packages/app
```

### `--debug`

`--debug`（或 `-d`）用于输出额外的调试信息。

```bash
rs staged --debug
```

### `--no-stash`

`--no-stash` 会禁用备份 stash，并在任务失败时跳过自动还原。

```bash
rs staged --no-stash
```

### `--quiet`

`--quiet`（或 `-q`）用于禁用 lint-staged 自身的控制台输出。

```bash
rs staged --quiet
```

### `--relative`

`--relative`（或 `-r`）会将相对于工作目录的文件路径传递给任务。

```bash
rs staged --relative
```

### `--verbose`

`--verbose`（或 `-v`）会在任务成功时也显示其输出；默认仅显示失败任务的输出。

```bash
rs staged --verbose
```

### `--help`

`--help`（或 `-h`）用于显示命令的用法和选项。

```bash
rs staged --help
```

## 配置 \{#configuration}

在 [Rstack 配置文件](/zh/guide/configuration.md#configuration-file)中通过 [`define.staged()`](/zh/guide/configuration.md#define-staged) 配置暂存文件任务。该 API 支持标准的 [lint-staged 配置](https://github.com/lint-staged/lint-staged#configuration)：

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

define.staged({
  '*.{js,jsx,ts,tsx}': ['rs lint', 'rs fmt'],
  '*.{json,md,mdx,css,html}': 'rs fmt',
});
```



---
url: /zh/index.md
---

> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/index.md.

![background](https://assets.rspack.rs/rspack/assets/landingpage-background-compressed.png)

![logo](https://assets.rspack.rs/rspack/rspack-logo.svg)

# Rstack CLI

统一的 JavaScript 工具链

一个命令行、一份配置、一致的工作流

快速上手[GitHubGitHub](https://github.com/rstackjs/rstack-cli)

[![统一命令行](/static/svg/Speedometer.e6ce5b2c32.svg)### 统一命令行

通过 rs 命令完成开发、构建、测试、检查、格式化、库构建和文档开发。

](/zh/guide/quick-start#cli-commands)

[![统一配置](/static/svg/Lightning.7b8c41ecd3.svg)### 统一配置

在一份 rstack.config.ts 中配置完整工具链。

](/zh/guide/configuration)

[![Rstack 驱动](/static/svg/FrameCheck.ccc904a9ef.svg)### Rstack 驱动

基于 Rspack、Rsbuild、Rslib、Rstest、Rslint 和 Rspress。

](/zh/guide/configuration)

[![融入现有工作流](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMTI4IDEyOCIgd2lkdGg9IjQyNCIKICBoZWlnaHQ9IjQyNCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ieE1pZFlNaWQgbWVldCIKICBzdHlsZT0id2lkdGg6IDEwMCU7IGhlaWdodDogMTAwJTsgdHJhbnNmb3JtOiB0cmFuc2xhdGUzZCgwcHgsIDBweCwgMHB4KTsgY29udGVudC12aXNpYmlsaXR5OiB2aXNpYmxlOyBiYWNrZ3JvdW5kLWNvbG9yOiB0cmFuc3BhcmVudDsiPgogIDxkZWZzPgogICAgPGNsaXBQYXRoIGlkPSJfX2xvdHRpZV9lbGVtZW50XzMzIj4KICAgICAgPHJlY3Qgd2lkdGg9IjEyOCIgaGVpZ2h0PSIxMjgiIHg9IjAiIHk9IjAiIC8+CiAgICA8L2NsaXBQYXRoPgogIDwvZGVmcz4KICA8ZyBjbGlwLXBhdGg9InVybCgjX19sb3R0aWVfZWxlbWVudF8zMykiPgogICAgPGcgdHJhbnNmb3JtPSJtYXRyaXgoMC43NDAwMDAwMDk1MzY3NDMyLDAsMCwwLjc0MDAwMDAwOTUzNjc0MzIsMjMuMjk5OTk5MjM3MDYwNTQ3LDM4Ljg0MDAwMDE1MjU4Nzg5KSIgb3BhY2l0eT0iMSIKICAgICAgc3R5bGU9ImRpc3BsYXk6IGJsb2NrOyI+CiAgICAgIDxnIG9wYWNpdHk9IjEiIHRyYW5zZm9ybT0ibWF0cml4KDEsMCwwLDEsMjcsMzQpIj4KICAgICAgICA8cGF0aCBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0ibWl0ZXIiIGZpbGwtb3BhY2l0eT0iMCIgc3Ryb2tlLW1pdGVybGltaXQ9IjQiCiAgICAgICAgICBzdHJva2U9InJnYigyNTUsMTM4LDApIiBzdHJva2Utb3BhY2l0eT0iMSIgc3Ryb2tlLXdpZHRoPSI1IgogICAgICAgICAgZD0iIE0xMCwtMjcgQzEwLC0yNyAxNCwtMjcgMTQsLTI3IEMxNi44Mjc5OTkxMTQ5OTAyMzQsLTI3IDE4LjI0MzAwMDAzMDUxNzU3OCwtMjcgMTkuMTIxMDAwMjg5OTE2OTkyLC0yNi4xMjEwMDAyODk5MTY5OTIgQzIwLC0yNS4yNDMwMDAwMzA1MTc1NzggMjAsLTIzLjgyNzk5OTExNDk5MDIzNCAyMCwtMjEgQzIwLC0yMSAyMCwtMTMuNSAyMCwtMTMuNSBNLTEwLC0yNyBDLTEwLC0yNyAtMTQsLTI3IC0xNCwtMjcgQy0xNi44Mjc5OTkxMTQ5OTAyMzQsLTI3IC0xOC4yNDMwMDAwMzA1MTc1NzgsLTI3IC0xOS4xMjEwMDAyODk5MTY5OTIsLTI2LjEyMTAwMDI4OTkxNjk5MiBDLTIwLC0yNS4yNDMwMDAwMzA1MTc1NzggLTIwLC0yMy44Mjc5OTkxMTQ5OTAyMzQgLTIwLC0yMSBDLTIwLC0yMSAtMjAsLTEzLjUgLTIwLC0xMy41IE0tMjAsMTMuNSBDLTIwLDEzLjUgLTIwLDIxIC0yMCwyMSBDLTIwLDIzLjgyNzk5OTExNDk5MDIzNCAtMjAsMjUuMjQzMDAwMDMwNTE3NTc4IC0xOS4xMjEwMDAyODk5MTY5OTIsMjYuMTIxMDAwMjg5OTE2OTkyIEMtMTguMjQzMDAwMDMwNTE3NTc4LDI3IC0xNi44Mjc5OTkxMTQ5OTAyMzQsMjcgLTE0LDI3IEMtMTQsMjcgLTEwLDI3IC0xMCwyNyBNMTAsMjcgQzEwLDI3IDE0LDI3IDE0LDI3IEMxNi44Mjc5OTkxMTQ5OTAyMzQsMjcgMTguMjQzMDAwMDMwNTE3NTc4LDI3IDE5LjEyMTAwMDI4OTkxNjk5MiwyNi4xMjEwMDAyODk5MTY5OTIgQzIwLDI1LjI0MzAwMDAzMDUxNzU3OCAyMCwyMy44Mjc5OTkxMTQ5OTAyMzQgMjAsMjEgQzIwLDIxIDIwLDEzLjUgMjAsMTMuNSIgLz4KICAgICAgPC9nPgogICAgPC9nPgogICAgPGcgdHJhbnNmb3JtPSJtYXRyaXgoMC43NDAwMDAwMDk1MzY3NDMyLDAsMCwwLjc0MDAwMDAwOTUzNjc0MzIsNjQuNzM5OTk3ODYzNzY5NTMsMzguODQwMDAwMTUyNTg3ODkpIiBvcGFjaXR5PSIxIgogICAgICBzdHlsZT0iZGlzcGxheTogYmxvY2s7Ij4KICAgICAgPGcgb3BhY2l0eT0iMSIgdHJhbnNmb3JtPSJtYXRyaXgoMSwwLDAsMSwyNywzNCkiPgogICAgICAgIDxwYXRoIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJtaXRlciIgZmlsbC1vcGFjaXR5PSIwIiBzdHJva2UtbWl0ZXJsaW1pdD0iNCIKICAgICAgICAgIHN0cm9rZT0icmdiKDI1NSwxMzgsMCkiIHN0cm9rZS1vcGFjaXR5PSIxIiBzdHJva2Utd2lkdGg9IjUiCiAgICAgICAgICBkPSIgTS0yMCwtMTMuNSBDLTIwLC0xMy41IC0yMCwtMjEgLTIwLC0yMSBDLTIwLC0yMy44Mjc5OTkxMTQ5OTAyMzQgLTIwLC0yNS4yNDMwMDAwMzA1MTc1NzggLTE5LjEyMTAwMDI4OTkxNjk5MiwtMjYuMTIxMDAwMjg5OTE2OTkyIEMtMTguMjQzMDAwMDMwNTE3NTc4LC0yNyAtMTYuODI3OTk5MTE0OTkwMjM0LC0yNyAtMTQsLTI3IEMtMTQsLTI3IDE0LC0yNyAxNCwtMjcgQzE2LjgyNzk5OTExNDk5MDIzNCwtMjcgMTguMjQzMDAwMDMwNTE3NTc4LC0yNyAxOS4xMjEwMDAyODk5MTY5OTIsLTI2LjEyMTAwMDI4OTkxNjk5MiBDMjAsLTI1LjI0MzAwMDAzMDUxNzU3OCAyMCwtMjMuODI3OTk5MTE0OTkwMjM0IDIwLC0yMSBDMjAsLTIxIDIwLDIxIDIwLDIxIEMyMCwyMy44Mjc5OTkxMTQ5OTAyMzQgMjAsMjUuMjQzMDAwMDMwNTE3NTc4IDE5LjEyMTAwMDI4OTkxNjk5MiwyNi4xMjEwMDAyODk5MTY5OTIgQzE4LjI0MzAwMDAzMDUxNzU3OCwyNyAxNi44Mjc5OTkxMTQ5OTAyMzQsMjcgMTQsMjcgQzE0LDI3IC0xNCwyNyAtMTQsMjcgQy0xNi44Mjc5OTkxMTQ5OTAyMzQsMjcgLTE4LjI0MzAwMDAzMDUxNzU3OCwyNyAtMTkuMTIxMDAwMjg5OTE2OTkyLDI2LjEyMTAwMDI4OTkxNjk5MiBDLTIwLDI1LjI0MzAwMDAzMDUxNzU3OCAtMjAsMjMuODI3OTk5MTE0OTkwMjM0IC0yMCwyMSBDLTIwLDIxIC0yMCwxMy41IC0yMCwxMy41IiAvPgogICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyB0cmFuc2Zvcm09Im1hdHJpeCgwLjc0MDAwMDAwOTUzNjc0MzIsMCwwLDAuNzQwMDAwMDA5NTM2NzQzMiw0MC42ODk5OTg2MjY3MDg5ODQsNTIuOTAwMDAxNTI1ODc4OTA2KSIgb3BhY2l0eT0iMSIKICAgICAgc3R5bGU9ImRpc3BsYXk6IGJsb2NrOyI+CiAgICAgIDxnIG9wYWNpdHk9IjEiIHRyYW5zZm9ybT0ibWF0cml4KDEsMCwwLDEsNTguNSwxNSkiPgogICAgICAgIDxwYXRoIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgZmlsbC1vcGFjaXR5PSIwIiBzdHJva2U9InJnYigyNDksNTcsMzIpIiBzdHJva2Utb3BhY2l0eT0iMSIKICAgICAgICAgIHN0cm9rZS13aWR0aD0iNiIgZD0iIE0tNCw4IEMtNCw4IDQsMCA0LDAgQzQsMCAtNCwtOCAtNCwtOCIgLz4KICAgICAgPC9nPgogICAgICA8ZyBvcGFjaXR5PSIxIiB0cmFuc2Zvcm09Im1hdHJpeCgxLDAsMCwxLDAsMCkiPgogICAgICAgIDxwYXRoIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJtaXRlciIgZmlsbC1vcGFjaXR5PSIwIiBzdHJva2UtbWl0ZXJsaW1pdD0iNCIKICAgICAgICAgIHN0cm9rZT0icmdiKDI0OSw1NywzMikiIHN0cm9rZS1vcGFjaXR5PSIxIiBzdHJva2Utd2lkdGg9IjYiIGQ9IiBNMy41LDE1IEMzLjUsMTUgNjIuNSwxNSA2Mi41LDE1IiAvPgogICAgICA8L2c+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4=)### 融入现有工作流

继续使用你熟悉的运行时、包管理器和任务编排工具。

](/zh/guide/quick-start)

# Rstack

高性能、一体化的 JavaScript 工具链，为开发者与 Agent 打造

[![Rspack](https://assets.rspack.rs/rspack/rspack-logo.svg)Rspack基于 Rust 编写的高性能 Web 打包工具，提供现代化的 webpack API

rspack.rs](https://rspack.rs)[![Rsbuild](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)Rsbuild基于 Rspack 的现代 Web 构建工具，快速且易于扩展

rsbuild.rs](https://rsbuild.rs)[![Rslib](https://assets.rspack.rs/rslib/rslib-logo.svg)Rslib基于 Rsbuild 的库开发工具，以简单的方式创建 JavaScript 库和 UI 组件库

rslib.rs](https://rslib.rs)[![Rspress](https://assets.rspack.rs/rspress/rspress-logo-480x480.png)Rspress基于 Rsbuild 的静态站点生成器，用于创建优雅的文档站点

rspress.rs](https://rspress.rs)[![Rsdoctor](https://assets.rspack.rs/rsdoctor/rsdoctor-logo-480x480.png)RsdoctorAI 友好的构建分析工具，使构建流程变得透明、可预测和可优化

rsdoctor.rs](https://rsdoctor.rs)[![Rstest](https://assets.rspack.rs/rstest/rstest-logo.svg)Rstest基于 Rspack 的 JavaScript 测试框架，兼容 Jest API

rstest.rs](https://rstest.rs/)[![Rslint](https://assets.rspack.rs/rslint/rslint-logo.svg)Rslint高性能 JavaScript 和 TypeScript 代码检查工具，兼容 ESLint 生态

rslint.rs](https://rslint.rs/)

## 指南

- [快速上手](/zh/guide/quick-start)
- [配置](/zh/guide/configuration)

## 命令

- [rs build](/zh/guide/cli/build)
- [rs lib](/zh/guide/cli/lib)
- [rs test](/zh/guide/cli/test)
- [rs lint](/zh/guide/cli/lint)
- [rs doc](/zh/guide/cli/doc)

## 生态

- [Rsbuild](https://rsbuild.rs/)
- [Rslib](https://rslib.rs/)
- [Rstest](https://rstest.rs/)
- [Rslint](https://rslint.rs/)
- [Rspress](https://rspress.rs/)

## 社区

- [GitHub](https://github.com/rstackjs/rstack-cli)
- [npm](https://www.npmjs.com/package/rstack)
- [Discord](https://discord.gg/XsaKEEk4mW)

Rstack CLI is free and open source software released under the MIT license.

© 2026 Rstack contributors.