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

# Use Rspress

[Rspress](https://rspress.rs/) is a Rspack-based static site generator, ideal for building demos and API docs for component libraries. With [plugin-preview](https://rspress.rs/plugin/official-plugins/preview) and [plugin-api-docgen](https://rspress.rs/plugin/official-plugins/api-docgen), you can reuse Rslib sources and typings to preview components and view APIs in one site.

## New project

:::info
When using `create-rslib`, choose the React + TypeScript template and enable the extra tool **“Rspress - documentation”** to auto-generate docs folder, scripts, and Rspress config—no manual setup needed.
:::

Run `npm create rslib@latest` and select Rspress to get the following structure:

```tree
├── docs
│   └── index.mdx
├── src
│   └── Button.tsx
├── package.json
├── tsconfig.json
├── rslib.config.ts
└── rspress.config.ts
```

The template includes [rsbuild-plugin-workspace-dev](https://github.com/rstackjs/rsbuild-plugin-workspace-dev), which will run Rslib watch while the Rspress dev server is running.

Run `npm run doc` to start the Rspress dev server and preview your Rslib components:

```json title="package.json"
{
  "scripts": {
    "dev": "rslib --watch",
    "doc": "rspress dev" // run this, it also runs the dev script
  }
}
```

## Existing project

If you are using Rslib to build a component library, follow these steps to add Rspress documentation support.


### Install deps

```sh [npm]
npm add @rspress/core @rspress/plugin-api-docgen @rspress/plugin-preview rsbuild-plugin-workspace-dev -D
```

```sh [yarn]
yarn add @rspress/core @rspress/plugin-api-docgen @rspress/plugin-preview rsbuild-plugin-workspace-dev -D
```

```sh [pnpm]
pnpm add @rspress/core @rspress/plugin-api-docgen @rspress/plugin-preview rsbuild-plugin-workspace-dev -D
```

```sh [bun]
bun add @rspress/core @rspress/plugin-api-docgen @rspress/plugin-preview rsbuild-plugin-workspace-dev -D
```

```sh [deno]
deno add npm:@rspress/core npm:@rspress/plugin-api-docgen npm:@rspress/plugin-preview npm:rsbuild-plugin-workspace-dev -D
```
### Add scripts in `package.json`
```json title="package.json"
{
  "name": "@your-scope/your-package",
  "version": "0.1.0",
  "scripts": {
    "dev": "rslib --watch",
    "build": "rslib",
    "doc": "rspress dev", // [!code highlight]
    "doc:build": "rspress build", // [!code highlight]
    "doc:preview": "rspress preview" // [!code highlight]
  }
}
```
### Create `rspress.config.ts`
Add preview-related plugins like [plugin-preview](https://rspress.rs/plugin/official-plugins/preview) and [plugin-api-docgen](https://rspress.rs/plugin/official-plugins/api-docgen).
```ts title="rspress.config.ts"
import * as path from 'node:path';
import { defineConfig } from '@rspress/core';
import { pluginApiDocgen } from '@rspress/plugin-api-docgen';
import { pluginPreview } from '@rspress/plugin-preview';
import { pluginWorkspaceDev } from 'rsbuild-plugin-workspace-dev';

export default defineConfig({
  root: path.join(__dirname, 'docs'),
  title: 'Component Library Docs',
  lang: 'en',
  builderConfig: {
    plugins: [
      pluginWorkspaceDev({
        startCurrent: true, // run current package dev/watch when docs start
      }),
    ],
  },
  plugins: [
    pluginApiDocgen({
      entries: {
        Button: './src/Button.tsx',
      },
      apiParseTool: 'react-docgen-typescript',
    }),
    pluginPreview(),
  ],
});
```
### Import built output by package name
Set `paths` in `tsconfig.json` to point to your package, or declare your package as a dependency via `"workspace:*"` in `package.json`, so `plugin-preview` resolves demos from the built artifact.
```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      // [!code highlight:1]
      "@your-scope/your-package": ["."]
    }
  },
  "include": ["src", "docs", "rspress.config.ts", "rslib.config.ts"]
}
```
:::tip
In [plugin-preview](https://rspress.rs/plugin/official-plugins/preview), we recommend importing component outputs by package name rather than relative paths. This keeps the preview environment consistent with how users consume the library.
If your project uses the `exports` field, we recommend `"workspace:*"` instead:
```json title="package.json"
{
  "name": "@your-scope/your-package",
  "version": "0.1.0",
  "dependencies": {
    // [!code highlight:1]
    "@your-scope/your-package": "workspace:*"
  }
}
```
This approach avoids changes to `tsconfig.json` and supports multi-entry exports.
:::
### Example
Add docs under `docs/` (see the template’s `docs/Button.mdx`):
````mdx title="docs/Button.mdx"
# Button

## Size

```jsx preview
import { Button } from '@your-scope/your-package';

export default () => <Button size="medium" label="Click me" />;
```

## Background

```jsx preview
import { Button } from '@your-scope/your-package';

export default () => <Button backgroundColor="red" label="Red" />;
```

## API

<API moduleName="Button" />
````

## References

- [Rspress docs & plugins](https://rspress.rs/)
- [`rsbuild-plugin-workspace-dev`](https://www.npmjs.com/package/rsbuild-plugin-workspace-dev)
- [`@rspress/plugin-api-docgen`](https://rspress.rs/plugin/official-plugins/api-docgen)
- [`@rspress/plugin-preview`](https://rspress.rs/plugin/official-plugins/preview)