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

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

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

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

Rstack CLI 支持使用 [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 版本要求

Rstack CLI 要求 Node.js 22.18.0+ 或 24.3.0+。

:::

## 创建 Rstack 项目 \{#create-a-rstack-project}

使用 [create-rstack](https://www.npmjs.com/package/create-rstack) 可以快速创建已配置好 Rstack 的应用、库、文档站点或 monorepo。推荐使用 [pnpm](https://pnpm.io/) 作为包管理器。


```sh [pnpm]
pnpm create rstack@latest
```

```sh [npm]
npm create rstack@latest
```

```sh [yarn]
yarn create rstack
```

```sh [bun]
bun create rstack@latest
```

```sh [deno]
deno init --npm rstack@latest
```

按照提示操作即可完成创建。

项目创建完成后，执行以下步骤：

- 执行 `pnpm install`（或其他包管理器的 install 命令）安装依赖。
- 执行 `pnpm run dev` 启动开发服务器或监听模式。

### 模板 \{#templates}

创建项目时，可选择 `create-rstack` 提供的下列模板：

| 项目类型     | 模板                                              |
| -------- | ----------------------------------------------- |
| Web 应用   | 原生 JavaScript、React、Preact、Vue、Lit、Svelte、Solid |
| 库        | Node.js、React、Vue、Svelte、Solid                  |
| 文档站点     | 单语言、多语言                                         |
| Monorepo | Turborepo                                       |

所有应用和库模板均提供 JavaScript 和 TypeScript 版本。

### 当前目录 \{#current-directory}

如需在当前目录中创建项目，将项目名称或路径设置为 `.`：

```
◆  Create Rstack Project
│
◇  Project name or path
│  .
│
◇  "." is not empty, please choose:
│  Continue and override files
```

### 非交互模式 \{#non-interactive-mode}

[create-rstack](https://www.npmjs.com/package/create-rstack) 支持通过命令行选项进入非交互模式。该模式会跳过提示并直接创建项目，适合脚本、CI 和自动化场景。

例如，以下命令将在 `my-project` 目录中创建一个 TypeScript React 应用：

```bash
npx -y create-rstack@latest my-project --template app-react-ts

# 使用缩写
npx -y create-rstack@latest my-project -t app-react-ts

# 跳过 Git 仓库初始化
npx -y create-rstack@latest my-project -t app-react-ts --no-git
```

`create-rstack` 支持的全部 CLI 选项如下：

```text wrapCode
Usage: create-rstack [dir] [options]

Options:
  -h, --help                display help for command
  -d, --dir <dir>           create project in specified directory
  -t, --template <tpl>      specify the template to use
  --no-git                  skip Git repository initialization
  --override                override files in target directory
  --package-name <name>     specify the package name
  --template-version <ver>  specify the npm template version

Available templates: app-vanilla, app-vanilla-ts, app-react, app-react-ts, app-preact, app-preact-ts, app-vue, app-vue-ts, app-lit, app-lit-ts, app-svelte, app-svelte-ts, app-solid, app-solid-ts, lib-node, lib-node-ts, lib-react, lib-react-ts, lib-vue, lib-vue-ts, lib-svelte, lib-svelte-ts, lib-solid, lib-solid-ts, doc, doc-i18n, turborepo
```

## 迁移现有项目 \{#migrate-an-existing-project}

如需将现有项目迁移到 Rstack CLI，请参阅[迁移指南](/zh/guide/migration.md)，了解支持的工具和迁移 Skill 的使用方式。

## 安装 Rstack CLI \{#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",
    "check": "rs check",
    "lint": "rs lint",
    "format": "rs fmt"
  }
}
```

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

Rstack CLI 提供以下命令：

- [`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 check`](/zh/guide/cli/check.md)：运行 lint 和格式检查，并可选启用 TypeScript 类型检查。
- [`rs lint`](/zh/guide/cli/lint.md)：使用 Rslint 检查源代码。
- [`rs fmt`](/zh/guide/cli/fmt.md)：格式化代码。
- [`rs hooks`](/zh/guide/cli/hooks.md)：安装、更新或卸载仓库级 Git hooks。
- [`rs staged`](/zh/guide/cli/staged.md)：使用 lint-staged 对 Git 暂存区中的文件运行任务。

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

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

```ts title="rstack.config.ts"
// 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)。