For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt, and this page is available as Markdown at https://rspress.rs/plugin/official-plugins/client-redirects.md.
close
Rspress
  • English

      • @rspress/plugin-client-redirects
      Source Code

      Used for client redirects.

      Production only

      This plugin is always inactive in development and only active in production because it works on the build output.

      Warning

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

      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',
        },
      ],
    }),
  ],
});