# How to Handle Client-Side Redirects in Docusaurus: A Complete Guide
> Master Docusaurus client-side redirects with `@docusaurus/plugin-client-redirects` for seamless URL forwarding using meta-refresh and JavaScript. Enhance user experience now.
- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04
---
**Use the `@docusaurus/plugin-client-redirects` package to generate static HTML pages that forward visitors to new URLs using a meta-refresh tag and JavaScript location assignment.**
Docusaurus provides a dedicated plugin for handling URL migrations without requiring server-side configuration. This solution generates lightweight HTML files at build time that instantly redirect users to target routes, making it ideal for static hosting environments like GitHub Pages or Netlify where `.htaccess` or nginx rules are unavailable.
## How Client-Side Redirects Work in Docusaurus
The `@docusaurus/plugin-client-redirects` plugin operates exclusively during production builds. It analyzes your routing configuration, validates redirect rules, and writes standalone HTML files to the output directory that execute immediate browser redirects.
### The RedirectItem Type and Validation
Each redirect is defined as a `RedirectItem` object specifying `from` and `to` paths. According to the type definitions in [`packages/docusaurus-plugin-client-redirects/src/types.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-client-redirects/src/types.ts), these items must pass validation through the `PathnameSchema` using Joi.
The `validateRedirect` function in [`packages/docusaurus-plugin-client-redirects/src/redirectValidation.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-client-redirects/src/redirectValidation.ts) enforces that all paths are valid URL pathnames before generation proceeds. This prevents broken redirects from entering your build output.
### HTML Generation and Meta Refresh
For every valid redirect, the plugin generates an HTML file using the template defined in [`packages/docusaurus-plugin-client-redirects/src/templates/redirectPage.template.html.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-client-redirects/src/templates/redirectPage.template.html.ts). The generated page includes:
- A `` tag pointing to the target URL
- A canonical `` element referencing the destination (preserving SEO value)
- A JavaScript snippet executing `window.location.href` assignment for immediate forwarding
When `searchAnchorForwarding` is enabled, the script appends the original query string and hash fragment to the target URL before navigation.
### Build Pipeline Integration
During the build phase, the plugin receives the complete route manifest from Docusaurus. It processes any `fromExtensions` and `toExtensions` transformations, merges user-provided static redirects with dynamically generated ones from the `createRedirects` callback, and writes the final redirect pages into the `outDir`. These files deploy alongside your application code, requiring no server configuration to function.
## Installation and Configuration
Install the plugin as a dependency in your Docusaurus project:
```bash
npm install --save @docusaurus/plugin-client-redirects
```
Configure the plugin in your [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) file:
```javascript
export default {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
redirects: [
{from: '/old-page', to: '/new-page'},
],
},
],
],
};
```
### Basic Static Redirects
Define explicit path mappings using the `redirects` array. You can map multiple source URLs to a single destination:
```javascript
{
redirects: [
{
from: ['/legacy-a', '/legacy-b'],
to: '/updated',
},
],
}
```
### Extension-Based Redirects
Handle legacy file extensions automatically using `fromExtensions` and `toExtensions`:
```javascript
{
fromExtensions: ['html', 'htm'], // /docs/intro.html → /docs/intro
toExtensions: ['pdf'], // /report → /report.pdf
}
```
The plugin strips specified extensions from incoming requests and optionally appends extensions to target paths when the corresponding files exist in the build output.
### Dynamic Redirect Creation
Use the `createRedirects` callback to generate rules programmatically based on existing routes. This function receives each generated path (the "to" destination) and returns the "from" path(s) that should redirect to it:
```javascript
{
createRedirects(existingPath) {
if (existingPath.startsWith('/blog/')) {
return existingPath.replace('/blog/', '/news/');
}
return undefined; // Skip redirect creation for this path
},
}
```
Return a string, array of strings, or falsy value to control which redirects are created.
### Query String and Hash Forwarding
Preserve original URL parameters during redirection by enabling `searchAnchorForwarding`:
```javascript
{
searchAnchorForwarding: true,
}
```
When active, the client-side script concatenates `window.location.search` and `window.location.hash` to the target URL, ensuring users land on the correct anchor or filtered view after the redirect completes.
## When to Use Client-Side vs Server-Side Redirects
Client-side redirects require the browser to load an intermediate HTML file before reaching the destination, adding an HTTP round-trip. If your hosting provider supports native redirects (such as Netlify's `_redirects` file or Vercel's [`vercel.json`](https://github.com/facebook/docusaurus/blob/main/vercel.json)), use those instead for better performance.
Reserve the Docusaurus client-side redirect plugin for situations where server-side configuration is impossible, such as GitHub Pages deployments or shared hosting environments without rewrite rule support.
## Summary
- **Install** `@docusaurus/plugin-client-redirects` to enable static redirect generation
- **Define redirects** using the `redirects` array for static mappings or `createRedirects` for dynamic logic
- **Validate paths** automatically through Joi schemas in [`redirectValidation.ts`](https://github.com/facebook/docusaurus/blob/main/redirectValidation.ts) before build completion
- **Generate HTML** files containing meta-refresh tags and JavaScript location assignments at build time
- **Enable** `searchAnchorForwarding` to preserve query parameters and hash fragments during redirection
- **Deploy** redirect files alongside your static build to any hosting provider without server configuration
## Frequently Asked Questions
### Do client-side redirects work in Docusaurus development mode?
No, the plugin is inactive during development (`docusaurus start`) and only executes during production builds. Redirect pages are generated as static HTML files in the build output, so you must run `docusaurus build` and serve the resulting `build` directory to test redirect functionality.
### Can I redirect multiple old URLs to one new URL?
Yes, the `from` property in a `RedirectItem` accepts either a single string or an array of strings. Map multiple legacy paths to a single destination by providing an array of source URLs, as implemented in the plugin's type definitions in [`packages/docusaurus-plugin-client-redirects/src/types.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-client-redirects/src/types.ts).
### How do I preserve query parameters during a redirect?
Enable the `searchAnchorForwarding` configuration option set to `true`. This modifies the generated template in [`redirectPage.template.html.ts`](https://github.com/facebook/docusaurus/blob/main/redirectPage.template.html.ts) to append `window.location.search` and `window.location.hash` to the target URL before executing the `window.location.href` assignment.
### Are client-side redirects SEO-friendly?
The generated redirect pages include a canonical `` tag pointing to the destination URL, signaling to search engines that the target page is the authoritative source. However, server-side 301 redirects remain the preferred method for SEO because they transfer link equity more effectively and eliminate the intermediate page load required by meta-refresh redirects.