Include docs redirects in the generated docs artifact (#2240)

Author: NWylynko

package-lock.json

@@ -23,6 +23,7 @@
     "@types/node": "^22.13.2",
     "concurrently": "^8.2.2",
     "glob": "^11.0.1",
+    "jsonc-parser": "^3.3.1",
     "prettier": "^3.2.5",
     "prettier-plugin-astro": "^0.14.0",
     "prettier-plugin-nginx": "^1.0.3",

package.json

@@ -258,6 +258,80 @@ title: MDX Doc
     expect(await fileExists(pathJoin('./dist/non-mdx-file.txt'))).toBe(false)
     expect(await fileExists(pathJoin('./dist/image.png'))).toBe(false)
   })
+
+  test('should copy over and process redirects', async () => {
+    const { tempDir, readFile } = await createTempFiles([
+      {
+        path: './docs/manifest.json',
+        content: JSON.stringify({
+          navigation: [],
+        }),
+      },
+      {
+        path: './redirects/static.json',
+        content: JSON.stringify([
+          {
+            source: '/docs/page-1',
+            destination: '/docs/page-2',
+            permanent: true,
+          },
+          {
+            source: '/docs/page-2',
+            destination: '/docs/page-3',
+            permanent: true,
+          },
+        ]),
+      },
+      {
+        path: './redirects/dynamic.jsonc',
+        content: JSON.stringify([
+          {
+            source: '/docs/login/:path*',
+            destination: '/docs/signin/:path*',
+            permanent: true,
+          },
+        ]),
+      },
+    ])
+
+    await build(
+      createConfig({
+        ...baseConfig,
+        basePath: tempDir,
+        validSdks: ['react'],
+        redirects: {
+          static: {
+            inputPath: '../redirects/static.json',
+            outputPath: '_redirects/static.json',
+          },
+          dynamic: {
+            inputPath: '../redirects/dynamic.jsonc',
+            outputPath: '_redirects/dynamic.jsonc',
+          },
+        },
+      }),
+    )
+
+    expect(JSON.parse(await readFile('./dist/_redirects/static.json'))).toEqual({
+      '/docs/page-1': {
+        source: '/docs/page-1',
+        destination: '/docs/page-3',
+        permanent: true,
+      },
+      '/docs/page-2': {
+        source: '/docs/page-2',
+        destination: '/docs/page-3',
+        permanent: true,
+      },
+    })
+    expect(JSON.parse(await readFile('./dist/_redirects/dynamic.jsonc'))).toEqual([
+      {
+        source: '/docs/login/:path*',
+        destination: '/docs/signin/:path*',
+        permanent: true,
+      },
+    ])
+  })
 })
 
 describe('Manifest Validation', () => {

scripts/build-docs.test.ts

@@ -70,6 +70,12 @@ import { insertFrontmatter } from './lib/plugins/insertFrontmatter'
 import { validateAndEmbedLinks } from './lib/plugins/validateAndEmbedLinks'
 import { validateIfComponents } from './lib/plugins/validateIfComponents'
 import { validateUniqueHeadings } from './lib/plugins/validateUniqueHeadings'
+import {
+  analyzeAndFixRedirects as optimizeRedirects,
+  readRedirects,
+  transformRedirectsToObject,
+  writeRedirects,
+} from './lib/redirects'
 
 // Only invokes the main function if we run the script directly eg npm run build, bun run ./scripts/build-docs.ts
 if (require.main === module) {
@@ -87,6 +93,16 @@ async function main() {
     partialsPath: '../docs/_partials',
     distPath: '../dist',
     typedocPath: '../clerk-typedoc',
+    redirects: {
+      static: {
+        inputPath: '../redirects/static/docs.json',
+        outputPath: '_redirects/static.json',
+      },
+      dynamic: {
+        inputPath: '../redirects/dynamic/docs.jsonc',
+        outputPath: '_redirects/dynamic.jsonc',
+      },
+    },
     ignoreLinks: [
       '/docs/core-1',
       '/docs/reference/backend-api',
@@ -166,6 +182,16 @@ export async function build(config: BuildConfig, store: Store = createBlankStore
 
   await ensureDir(config.distPath)
 
+  if (config.redirects) {
+    const { staticRedirects, dynamicRedirects } = await readRedirects(config)
+
+    const optimizedStaticRedirects = optimizeRedirects(staticRedirects)
+    const transformedStaticRedirects = transformRedirectsToObject(optimizedStaticRedirects)
+
+    await writeRedirects(config, transformedStaticRedirects, dynamicRedirects)
+    console.info('✓ Wrote redirects to disk')
+  }
+
   const userManifest = await getManifest()
   console.info('✓ Read Manifest')
 

scripts/build-docs.ts

@@ -24,6 +24,16 @@ type BuildConfigOptions = {
     collapseDefault: boolean
     hideTitleDefault: boolean
   }
+  redirects?: {
+    static: {
+      inputPath: string
+      outputPath: string
+    }
+    dynamic: {
+      inputPath: string
+      outputPath: string
+    }
+  }
   cleanDist: boolean
   flags?: {
     watch?: boolean
@@ -72,6 +82,19 @@ export function createConfig(config: BuildConfigOptions) {
       hideTitleDefault: false,
     },
 
+    redirects: config.redirects
+      ? {
+          static: {
+            inputPath: resolve(path.join(config.distPath, config.redirects.static.inputPath)),
+            outputPath: resolve(path.join(config.distPath, config.redirects.static.outputPath)),
+          },
+          dynamic: {
+            inputPath: resolve(path.join(config.distPath, config.redirects.dynamic.inputPath)),
+            outputPath: resolve(path.join(config.distPath, config.redirects.dynamic.outputPath)),
+          },
+        }
+      : null,
+
     cleanDist: config.cleanDist,
 
     flags: {

scripts/lib/config.ts

@@ -0,0 +1,74 @@
+import type { BuildConfig } from './config'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { parse as parseJSONC } from 'jsonc-parser'
+
+interface Redirect {
+  source: string
+  destination: string
+  permanent: boolean
+}
+
+export function transformRedirectsToObject(redirects: Redirect[]) {
+  return Object.fromEntries(redirects.map((item) => [item.source, item]))
+}
+
+export async function readRedirects(config: BuildConfig) {
+  const { static: staticConfig, dynamic: dynamicConfig } = config.redirects ?? {}
+  if (!staticConfig?.inputPath || !dynamicConfig?.inputPath) {
+    throw new Error('Redirect paths not configured')
+  }
+
+  const [staticContent, dynamicContent] = await Promise.all([
+    fs.readFile(staticConfig.inputPath, 'utf-8'),
+    fs.readFile(dynamicConfig.inputPath, 'utf-8'),
+  ])
+
+  return {
+    staticRedirects: JSON.parse(staticContent) as Redirect[],
+    dynamicRedirects: parseJSONC(dynamicContent) as Redirect[],
+  }
+}
+
+export function analyzeAndFixRedirects(redirects: Redirect[]): Redirect[] {
+  const redirectMap = new Map(redirects.map((r) => [r.source, r.destination]))
+  const finalDestinations = new Map<string, string>()
+
+  // Find final destinations for each redirect
+  for (const { source, destination, permanent } of redirects) {
+    let current = destination
+    const visited = new Set([source])
+
+    while (redirectMap.has(current) && !visited.has(current)) {
+      visited.add(current)
+      current = redirectMap.get(current)!
+    }
+
+    finalDestinations.set(source, current)
+  }
+
+  // Create new redirects pointing to final destinations
+  return redirects.map(({ source, permanent }) => ({
+    source,
+    destination: finalDestinations.get(source)!,
+    permanent,
+  }))
+}
+
+export async function writeRedirects(
+  config: BuildConfig,
+  staticRedirects: Record<string, Redirect>,
+  dynamicRedirects: Redirect[],
+) {
+  const { static: staticConfig, dynamic: dynamicConfig } = config.redirects ?? {}
+  if (!staticConfig?.outputPath || !dynamicConfig?.outputPath) {
+    throw new Error('Redirect output paths not configured')
+  }
+
+  await fs.mkdir(path.dirname(staticConfig.outputPath), { recursive: true })
+
+  await Promise.all([
+    fs.writeFile(staticConfig.outputPath, JSON.stringify(staticRedirects)),
+    fs.writeFile(dynamicConfig.outputPath, JSON.stringify(dynamicRedirects)),
+  ])
+}