close
Rspress
Guide
Plugin
API
Guide
Plugin
API

@rspress/plugin-client-redirects

Source

Used for client redirects.

Precautions

To ensure that the plugin works correctly, you need to set the fallback path in the server's deployment configuration to the 404.html page generated by Rspress.

For example:

nginx
location / {
  error_page 404 /404.html;
}
netlify.toml
[[redirects]]
from = "/*"
to = "/404.html"
status = 404

Installation

npm
yarn
pnpm
bun
npm add @rspress/plugin-client-redirects -D

Usage

Write the following configuration in the configuration file:

rspress.config.ts
import { pluginClientRedirects } from '@rspress/plugin-client-redirects';
import { defineConfig } from 'rspress/config';

export default defineConfig({
  pluginClientRedirects({
    redirects: [
      {
        from: '/docs/old1',
        to: '/docs/new1',
      },
    ],
  }),
});

Configuration

This plugin supports passing in an object configuration. The properties of this object configuration are as follows:

type RedirectRule = {
  from: string | string[];
  to: string;
};

type RedirectsOptions = {
  redirects?: RedirectRule[];
};

from represents the matching path, to represents the path to be redirected, and using regular expression strings is supported.

NOTE

One to supports matching multiple from: they will redirect to a single path.

One from cannot correspond to multiple to: there needs to be a unique and clear redirection path.

Example

import path from 'node:path';
import { defineConfig } from 'rspress/config';
import { pluginClientRedirects } from '@rspress/plugin-client-redirects';

export default defineConfig({
  root: path.join(__dirname, 'doc'),
  plugins: [
    pluginClientRedirects({
      redirects: [
        // /docs/old1 -> /docs/new1
        {
          from: '/docs/old1',
          to: '/docs/new1',
        },
        // redirect from multiple old paths to the new path
        {
          from: ['/docs/2022', '/docs/2023'],
          to: '/docs/2024',
        },
        // redirect using regular expressions
        {
          from: '^/docs/old2',
          to: '/docs/new2',
        },
        {
          from: '/docs/old3$',
          to: '/docs/new3',
        },
        // redirect to an external URL
        {
          from: '/docs/old4',
          to: 'https://example.com',
        },
      ],
    }),
  ],
});