> 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.

# @rspress/plugin-client-redirects 

[Source Code](https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-client-redirects)

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](https://rspress.rs/guide/basic/ssg.md#refresh-404) 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


```sh [npm]
npm add @rspress/plugin-client-redirects -D
```

```sh [yarn]
yarn add @rspress/plugin-client-redirects -D
```

```sh [pnpm]
pnpm add @rspress/plugin-client-redirects -D
```

```sh [bun]
bun add @rspress/plugin-client-redirects -D
```

```sh [deno]
deno add npm:@rspress/plugin-client-redirects -D
```

## Usage

Write the following configuration in the configuration file:

```ts title="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:

```ts
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

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