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

# Quick start


For your Agent

Start a Rspress project in one shot

Copy this prompt and send it to your AI agent. It will scaffold a new Rspress site for you automatically.

Copy Prompt

Create a Rspress project by following the official quick start guide at
https://rspress.rs/guide/start/getting-started.md.

1. Scaffold the project with `create rspress@latest`.
2. Install dependencies.
3. Start the dev server.

## Environment preparation

Rspress supports using [Node.js](https://nodejs.org/), [Deno](https://deno.com/), or [Bun](https://bun.sh/) as the JavaScript runtime.

Use one of the following installation guides to set up a runtime:

- [Install Node.js](https://nodejs.org/en/download)
- [Install Bun](https://bun.com/docs/installation)
- [Install Deno](https://docs.deno.com/runtime/getting_started/installation/)

:::tip Version requirements

Rspress requires Node.js version 20.19+, 22.12+.

:::

## Online example

You can try Rspress directly in [CodeSandbox](https://codesandbox.io/p/github/web-infra-dev/rspress-codesandbox-template/main).

## Create a Rspress project

The recommended way to start a new Rspress project is to use the `create-rspress` scaffold:


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

```sh [yarn]
yarn create rspress
```

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

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

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

The scaffold will ask for the project name or path, whether to set up i18n, whether to create a `theme` folder for customization, and which optional tools or skills to add.

After the project is created, follow the next steps printed in the terminal:

```bash
cd rspress-project
git init # optional
npm install
npm run dev
```

The dev server will print the local URL after startup. Open it in your browser to view the generated documentation site.

### Templates

Rspress provides the following built-in templates:

| Template      | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `basic`       | Creates a minimal Rspress documentation site that uses the default theme.   |
| `basic-theme` | Creates a single-language site with a `theme` folder for customization.     |
| `i18n`        | Creates a multilingual documentation site with English and Chinese content. |
| `i18n-theme`  | Creates a multilingual site with a `theme` folder for customization.        |

### Optional tools

During project creation, you can select optional tools for linting or formatting:

| Tool       | Purpose                                |
| ---------- | -------------------------------------- |
| `rslint`   | Adds Rslint for linting.               |
| `eslint`   | Adds ESLint for linting.               |
| `prettier` | Adds Prettier for formatting.          |
| `biome`    | Adds Biome for linting and formatting. |

### Optional skills

If you plan to maintain the documentation site with an AI agent, you can select optional Agent Skills during project creation. The CLI will generate a `.agents/skills` directory in your project and add the selected skills there.

For most documentation sites, we recommend selecting:

- [rspress-docs-generator](https://github.com/rstackjs/agent-skills#rspress-docs-generator): helps AI agents create and maintain Rspress documentation sites, especially when a monorepo keeps a dedicated Rspress project as its docs site.
- [rspress-best-practices](https://github.com/rstackjs/agent-skills#rspress-best-practices): provides Rspress project structure, config, MDX, theme, and deployment guidance for AI agents.
- [rspress-description-generator](https://github.com/rstackjs/agent-skills#rspress-description-generator): helps AI agents write and maintain page descriptions for SEO, search, and AI-readable outputs.

If you choose the `basic-theme` or `i18n-theme` template, the following skill is selected by default:

- [rspress-custom-theme](https://github.com/rstackjs/agent-skills#rspress-custom-theme): enables your AI agent to customize the Rspress theme, such as CSS variables, layout slots, and theme component overrides.

These skills do not affect the runtime behavior of your Rspress site. They only provide local guidance for AI agents when editing or maintaining the project. If you do not use an AI agent, you can deselect them or press Enter to skip this option.

For more information about Agent Skills and other AI-related capabilities, see [AI](/guide/start/ai.md).

### Current directory

To create a project in the current directory, enter `.` as the project path when prompted:

```bash
◆  Create Rspress Project

◇  Project name or path
│  .
```

If the current directory is not empty, the CLI will ask whether to continue and overwrite files.

### Non-interactive mode

You can pass CLI options to create a project without interactive prompts:

```bash
npx -y create-rspress@latest my-docs --template basic-theme --tools rslint,prettier
```

You can also scaffold the multilingual template:

```bash
npx -y create-rspress@latest my-docs --template i18n
```

Or scaffold a multilingual site with a `theme` folder:

```bash
npx -y create-rspress@latest my-docs --template i18n-theme
```

You can also add Agent Skills explicitly:

```bash
npx -y create-rspress@latest my-docs --template basic-theme --skill rspress-docs-generator,rspress-best-practices,rspress-description-generator
```

All CLI flags supported by `create-rspress`:

```bash
Usage: create-rspress [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
  --tools <tool>            add additional tools, comma separated
  --skill <skill>           add optional skills, comma separated
  --override                override files in target directory
  --packageName <name>      specify the package name
  --template-version <ver>  specify the npm template version

Available templates:
  basic, basic-theme, i18n, i18n-theme

Optional tools:
  eslint, rslint, biome, prettier

Optional skills:
  rspress-docs-generator, rspress-best-practices, rspress-custom-theme, rspress-description-generator
```

## Manual setup

If you want to add Rspress to an existing project or create the minimal files yourself, start by creating a directory:

```bash
mkdir rspress-app && cd rspress-app
```

Initialize a `package.json`:

```bash
npm init -y
```

Install Rspress:


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

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

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

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

```sh [deno]
deno add npm:@rspress/core -D
```

Create the first document:

```bash
mkdir docs && echo '# Hello world' > docs/index.md
```

Add the following scripts to `package.json`:

```json
{
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "preview": "rspress preview"
  }
}
```

Create a configuration file:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  root: 'docs',
});
```

Create `tsconfig.json`:

```json
{
  "compilerOptions": {
    "lib": ["DOM", "ES2023"],
    "jsx": "react-jsx",
    "target": "ES2023",
    "noEmit": true,
    "skipLibCheck": true,
    "useDefineForClassFields": true,

    /* modules */
    "module": "ESNext",
    "moduleDetection": "force",
    "moduleResolution": "bundler",
    "verbatimModuleSyntax": true,
    "resolveJsonModule": true,
    "allowImportingTsExtensions": true,
    "noUncheckedSideEffectImports": true,
    "isolatedModules": true,

    /* type checking */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["docs", "theme", "rspress.config.ts"],
  "mdx": {
    "checkMdx": true
  }
}
```

## Start dev server

Start the local development server with the following command:

```bash
npm run dev
```

:::tip TIP

For the dev command, you can specify the port number or host of the development server with the `--port` or `--host` parameter, such as `rspress dev --port 8080 --host 0.0.0.0`.

:::

## Build for production

Build the production bundle with the following command:

```bash
npm run build
```

By default, Rspress will output the production files to the `doc_build` directory.

## Preview locally

Start the local preview server with the following command:

```bash
npm run preview
```

The preview server serves the production output from `doc_build`.

## Next steps

- Read [Basic features](/guide/basic/conventional-route.md) to learn routing, homepages, static assets, deployment, and other common documentation site features.
- Read [Use MDX](/guide/use-mdx/components.md) to learn how to write MDX and use components in documentation.
- Read [Configuration](/api/config/config-basic.md) to learn all supported Rspress config options.