#Quick start

#Environment preparation

Rspress supports using Node.js, Deno, or Bun as the JavaScript runtime.

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

• Install Node.js
• Install Bun
• Install Deno

#Online example

You can try Rspress directly in CodeSandbox.

#Create a Rspress project

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

npm create rspress@latest

yarn create rspress

pnpm create rspress@latest

bun create rspress@latest

deno init --npm rspress@latest

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

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

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:

#Optional tools

During project creation, you can select optional tools for linting or 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-best-practices: provides Rspress project structure, config, MDX, theme, and deployment guidance for AI agents.
• rspress-description-generator: helps AI agents write and maintain page descriptions for SEO, search, and AI-readable outputs.

If you choose the custom-theme template, the following skill is selected by default:

• 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.

#Current directory

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

◆  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:

npx -y create-rspress@latest my-docs --template custom-theme --tools rslint,prettier

You can also add Agent Skills explicitly:

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

All CLI flags supported by create-rspress:

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, custom-theme

Optional tools:
  eslint, rslint, biome, prettier

Optional skills:
  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:

mkdir rspress-app && cd rspress-app

Initialize a package.json:

npm init -y

Install Rspress:

npm install @rspress/core -D

yarn add @rspress/core -D

pnpm add @rspress/core -D

bun add @rspress/core -D

deno add npm:@rspress/core -D

Create the first document:

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

Add the following scripts to package.json:

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

Create a configuration file:

import { defineConfig } from '@rspress/core';

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

Create tsconfig.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:

npm run dev

#Build for production

Build the production bundle with the following command:

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:

npm run preview

The preview server serves the production output from doc_build.

#Next steps

• Read Basic features to learn routing, home pages, static assets, deployment, and other common documentation site features.
• Read Use MDX to learn how to write MDX and use components in documentation.
• Read Configuration to learn all supported Rspress config options.