close
Rslib
  • English

      • Use Rspress

      Rspress is a Rspack-based static site generator, ideal for building demos and API docs for component libraries. With plugin-preview and plugin-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:

      docs
      index.mdx
      src
      Button.tsx
      package.json
      tsconfig.json
      rslib.config.ts
      rspress.config.ts

      The template includes 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:

      package.json
      {
  "scripts": {
    "dev": "rslib build --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

      npm
      yarn
      pnpm
      bun
      deno
      npm add @rspress/core @rspress/plugin-api-docgen @rspress/plugin-preview rsbuild-plugin-workspace-dev -D

      Add scripts in package.json

      package.json
      {
  "name": "@your-scope/your-package",
  "version": "0.1.0",
  "scripts": {
    "dev": "rslib build --watch",
    "build": "rslib build",
    "doc": "rspress dev",
    "doc:build": "rspress build",
    "doc:preview": "rspress preview"
  }
}

      Create rspress.config.ts

      Add preview-related plugins like plugin-preview and plugin-api-docgen.

      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.

      tsconfig.json
      {
  "compilerOptions": {
    "paths": {
      "@your-scope/your-package": ["."]
    }
  },
  "include": ["src", "docs", "rspress.config.ts", "rslib.config.ts"]
}
      Tip

      In plugin-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:

      package.json
      {
  "name": "@your-scope/your-package",
  "version": "0.1.0",
  "dependencies": {
    "@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):

      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