How to Handle Client-Side Redirects in Docusaurus: A Complete Guide

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, these items must pass validation through the PathnameSchema using Joi.

The validateRedirect function in 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. The generated page includes:

• A <meta http-equiv="refresh"> tag pointing to the target URL
• A canonical <link> 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:

npm install --save @docusaurus/plugin-client-redirects

Configure the plugin in your docusaurus.config.js file:

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:

{
  redirects: [
    {
      from: ['/legacy-a', '/legacy-b'],
      to: '/updated',
    },
  ],
}

Extension-Based Redirects

Handle legacy file extensions automatically using fromExtensions and toExtensions:

{
  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:

{
  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:

{
  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), 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 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.

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}