close
Rspress
  • English

      • @rspress/plugin-client-redirects
      Source Code

      Used for client redirects.

      Warning

      Before using this plugin, make sure your deployment environment has the fallback page correctly configured. See the SSG refresh-404 guide for details.

      Note: Client-side redirects differ from server-side redirects — the page will load first and then redirect (causing a brief flash), and SSR is not supported. If your deployment platform supports server-side redirects (301/302), prefer using that approach for better SEO and user experience.

      Installation

      npm
      yarn
      pnpm
      bun
      deno
      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/core';

export default defineConfig({
  plugins: [
    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/core';
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',
        },
      ],
    }),
  ],
});