fix(plugin-client-redirects): redirect before hydration

Author: SoonIter

e2e/fixtures/client-redirects/index.test.ts

@@ -1,13 +1,20 @@
 import { expect, test } from '@playwright/test';
-import { getPort, killProcess, runDevCommand } from '../../utils/runCommands';
+import {
+  getPort,
+  killProcess,
+  runBuildCommand,
+  runDevCommand,
+  runPreviewCommand,
+} from '../../utils/runCommands';
 
-test.describe('client redirects test', async () => {
+test.describe('client redirects production test', async () => {
   let appPort: number;
-  let app: Awaited<ReturnType<typeof runDevCommand>>;
+  let app: Awaited<ReturnType<typeof runPreviewCommand>>;
   test.beforeAll(async () => {
     const appDir = import.meta.dirname;
     appPort = await getPort();
-    app = await runDevCommand(appDir, appPort);
+    await runBuildCommand(appDir);
+    app = await runPreviewCommand(appDir, appPort);
   });
 
   test.afterAll(async () => {
@@ -23,6 +30,21 @@ test.describe('client redirects test', async () => {
     await expect(page).toHaveURL(`http://localhost:${appPort}/docs/new1`);
   });
 
+  test('Should redirect before hydration', async ({ page }) => {
+    await page.route('**/*', async route => {
+      if (route.request().resourceType() === 'script') {
+        await route.abort();
+      } else {
+        await route.continue();
+      }
+    });
+
+    await page.goto(`http://localhost:${appPort}/docs/old1`, {
+      waitUntil: 'domcontentloaded',
+    });
+    await expect(page).toHaveURL(`http://localhost:${appPort}/docs/new1`);
+  });
+
   test('Should redirect correctly - array', async ({ page }) => {
     await page.goto(`http://localhost:${appPort}/docs/2022`, {
       waitUntil: 'networkidle',
@@ -77,3 +99,29 @@ test.describe('client redirects test', async () => {
     await expect(page).toHaveURL(externalUrl);
   });
 });
+
+test.describe('client redirects development test', async () => {
+  let appPort: number;
+  let app: Awaited<ReturnType<typeof runDevCommand>>;
+
+  test.beforeAll(async () => {
+    const appDir = import.meta.dirname;
+    appPort = await getPort();
+    app = await runDevCommand(appDir, appPort);
+  });
+
+  test.afterAll(async () => {
+    if (app) {
+      await killProcess(app);
+    }
+  });
+
+  test('Should be inactive in development', async ({ page }) => {
+    const sourceUrl = `http://localhost:${appPort}/docs/old1`;
+
+    await page.goto(sourceUrl, {
+      waitUntil: 'networkidle',
+    });
+    await expect(page).toHaveURL(sourceUrl);
+  });
+});

packages/plugin-client-redirects/package.json

@@ -25,8 +25,7 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist",
-    "static"
+    "dist"
   ],
   "scripts": {
     "build": "rslib build",
@@ -38,9 +37,6 @@
     "@rslib/core": "1.0.0-beta.1",
     "@rspress/config": "workspace:*",
     "@types/node": "^22.8.1",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "react": "^19.2.8",
     "rsbuild-plugin-publint": "^1.0.0",
     "typescript": "^6.0.3"
   },

packages/plugin-client-redirects/src/index.ts

@@ -1,5 +1,5 @@
-import path from 'node:path';
 import type { RspressPlugin } from '@rspress/core';
+import { getInlineRedirectScript } from './inlineRedirect';
 import type { RedirectsOptions } from './types';
 
 /**
@@ -8,10 +8,29 @@ import type { RedirectsOptions } from './types';
 export function pluginClientRedirects(
   options: RedirectsOptions = {},
 ): RspressPlugin {
-  return {
+  const inlineRedirectScript = getInlineRedirectScript(options);
+
+  const plugin: RspressPlugin = {
     name: '@rspress/plugin-client-redirects',
-    globalUIComponents: [
-      [path.join(__dirname, '../static/Redirect.tsx'), options],
-    ],
+    config(config, _utils, isProd) {
+      plugin.builderConfig =
+        isProd && inlineRedirectScript
+          ? {
+              html: {
+                tags: [
+                  {
+                    tag: 'script',
+                    children: inlineRedirectScript,
+                    append: false,
+                  },
+                ],
+              },
+            }
+          : undefined;
+
+      return config;
+    },
   };
+
+  return plugin;
 }

packages/plugin-client-redirects/src/inlineRedirect.ts

@@ -0,0 +1,36 @@
+import type { RedirectsOptions } from './types';
+
+const serializeInlineScriptData = (value: unknown) =>
+  JSON.stringify(value).replace(/</g, '\\u003c');
+
+// Resolve redirects before the first render to avoid showing the source page
+// while waiting for React to hydrate.
+export function getInlineRedirectScript(
+  options: RedirectsOptions = {},
+): string {
+  const { redirects } = options;
+
+  if (!redirects?.length) {
+    return '';
+  }
+
+  return `{
+    var redirects = ${serializeInlineScriptData(redirects)}, pathname = window.location.pathname, hash = window.location.hash;
+    redirectLoop: for (var i = 0; i < redirects.length; i++) {
+      var redirect = redirects[i], patterns = Array.isArray(redirect.from) ? redirect.from : [redirect.from], to = redirect.to;
+      for (var j = 0; j < patterns.length; j++) {
+        var pattern = patterns[j];
+        try {
+          var regex = new RegExp(pattern);
+          if (regex.test(pathname)) {
+            var isExternal = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(to) && !/^(?:javascript|data|file):/i.test(to);
+            window.location.replace(isExternal ? to : pathname.replace(regex, to) + hash);
+            break redirectLoop;
+          }
+        } catch (error) {
+          console.warn('Invalid redirect pattern: ' + pattern, error);
+        }
+      }
+    }
+  }`.replace(/\n\s*/g, '');
+}

packages/plugin-client-redirects/static/Redirect.tsx

@@ -0,0 +1,132 @@
+import { describe, expect, test } from '@rstest/core';
+import { pluginClientRedirects } from '../src';
+import { getInlineRedirectScript } from '../src/inlineRedirect';
+import type { RedirectsOptions } from '../src/types';
+
+const runInlineRedirectScript = (
+  options: RedirectsOptions,
+  {
+    pathname,
+    hash = '',
+  }: {
+    pathname: string;
+    hash?: string;
+  },
+) => {
+  let redirectedTo: string | undefined;
+  const warnings: unknown[][] = [];
+  const script = getInlineRedirectScript(options);
+
+  Function(
+    'window',
+    'console',
+    script,
+  )(
+    {
+      location: {
+        pathname,
+        hash,
+        replace: (url: string) => {
+          redirectedTo = url;
+        },
+      },
+    },
+    {
+      warn: (...args: unknown[]) => {
+        warnings.push(args);
+      },
+    },
+  );
+
+  return { redirectedTo, script, warnings };
+};
+
+describe('getInlineRedirectScript', () => {
+  test('redirects internal routes and preserves the hash', () => {
+    expect(
+      runInlineRedirectScript(
+        {
+          redirects: [
+            {
+              from: ['/docs/2022', '/docs/2023'],
+              to: '/docs/2024',
+            },
+          ],
+        },
+        {
+          pathname: '/docs/2023/guide',
+          hash: '#install',
+        },
+      ).redirectedTo,
+    ).toBe('/docs/2024/guide#install');
+  });
+
+  test('redirects to external URLs', () => {
+    expect(
+      runInlineRedirectScript(
+        {
+          redirects: [
+            {
+              from: '/docs/old',
+              to: 'https://example.com/new',
+            },
+          ],
+        },
+        { pathname: '/docs/old' },
+      ).redirectedTo,
+    ).toBe('https://example.com/new');
+  });
+
+  test('warns for invalid patterns and continues matching', () => {
+    const result = runInlineRedirectScript(
+      {
+        redirects: [
+          {
+            from: ['[', '/docs/old'],
+            to: '/docs/new',
+          },
+        ],
+      },
+      { pathname: '/docs/old' },
+    );
+
+    expect(result.redirectedTo).toBe('/docs/new');
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0][0]).toBe('Invalid redirect pattern: [');
+  });
+
+  test('does not inject a script without redirect rules', () => {
+    expect(getInlineRedirectScript()).toBe('');
+    expect(getInlineRedirectScript({ redirects: [] })).toBe('');
+  });
+
+  test('escapes data that could close the inline script element', () => {
+    const script = getInlineRedirectScript({
+      redirects: [{ from: '</script>', to: '/docs/new' }],
+    });
+
+    expect(script).not.toContain('</script>');
+    expect(script).toContain('\\u003c/script>');
+  });
+});
+
+describe('pluginClientRedirects', () => {
+  test('only injects the redirect script in production', async () => {
+    const plugin = pluginClientRedirects({
+      redirects: [{ from: '/docs/old', to: '/docs/new' }],
+    });
+    const utils = {
+      addPlugin: () => {},
+      removePlugin: () => {},
+    };
+
+    await plugin.config?.({}, utils, false);
+    expect(plugin.builderConfig).toBeUndefined();
+
+    await plugin.config?.({}, utils, true);
+    expect(plugin.builderConfig?.html?.tags).toHaveLength(1);
+
+    await plugin.config?.({}, utils, false);
+    expect(plugin.builderConfig).toBeUndefined();
+  });
+});

packages/plugin-client-redirects/tests/inlineRedirect.test.ts

@@ -4,10 +4,14 @@ import { SourceCode, PackageManagerTabs } from '@rspress/core/theme';
 
 Used for client redirects.
 
+:::warning 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](/guide/basic/ssg#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.
+If your deployment platform supports server-side redirects (301/302), prefer using that approach for better SEO and user experience.
 :::
 
 ## Installation