fix(seo): redirect legacy comparison URLs to canonical pages

Google Search Console reported 404s for previously-indexed comparison
URLs that no longer match the canonical shape: inverse order, family-name
aliases (svelte->svelte5, vue->vue3, angular->angularRenaissance, etc.),
and missing trailing slashes. The redirect generator only covered inverse
pairs with a trailing slash, so those forms dropped to the 404 fallback.

Generate the full alias x order x slash matrix (686 rules) so every legacy
form 301s to its canonical page, extracted into a testable buildRedirectLines().

Author: matschik

build/generateRedirectsVitePlugin.ts

@@ -1,21 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import type { Plugin, ResolvedConfig } from "vite";
-import { frameworkVersions } from "../frameworks.ts";
-
-// canonicalPairs() uses the @frameworks alias which resolves at runtime via
-// the alias configured in svelte.config.js. For the Vite plugin (Node context)
-// we resolve it directly from the raw frameworks import, mirroring the same logic.
-function buildCanonicalPairs(): [string, string][] {
-  const ids = frameworkVersions.map((f) => f.id);
-  const pairs: [string, string][] = [];
-  for (let i = 0; i < ids.length; i++) {
-    for (let j = i + 1; j < ids.length; j++) {
-      pairs.push([ids[i], ids[j]]);
-    }
-  }
-  return pairs;
-}
+import { buildRedirectLines } from "./redirects.ts";
 
 export default function generateRedirectsVitePlugin(): Plugin {
   let resolvedOutDir = "dist";
@@ -32,8 +18,7 @@ export default function generateRedirectsVitePlugin(): Plugin {
       // Skip the SSR environment; write only once after the client build.
       if (this.environment?.name !== "client") return;
 
-      const pairs = buildCanonicalPairs();
-      const lines = pairs.map(([a, b]) => `/compare/${b}-vs-${a}/ /compare/${a}-vs-${b}/ 301`);
+      const lines = buildRedirectLines();
       const outPath = path.join(resolvedOutDir, "_redirects");
       try {
         await fs.mkdir(resolvedOutDir, { recursive: true });

build/redirects.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import { buildRedirectLines } from "./redirects";
+import { canonicalPairs } from "../src/lib/comparisonPairs";
+
+const lines = buildRedirectLines();
+
+/** source path -> redirect target, parsed from "<source> <target> 301". */
+const targetBySource = new Map(
+  lines.map((line) => {
+    const [source, target] = line.split(" ");
+    return [source, target] as const;
+  }),
+);
+
+describe("buildRedirectLines", () => {
+  // The exact URLs Google Search Console reported as 404 (Introuvable).
+  it.each([
+    ["/compare/react-vs-svelte5", "/compare/svelte5-vs-react/"], // inverse, no slash
+    ["/compare/svelte4-vs-svelte5", "/compare/svelte5-vs-svelte4/"], // inverse, no slash
+    ["/compare/aurelia1-vs-aurelia2", "/compare/aurelia2-vs-aurelia1/"], // inverse, no slash
+    ["/compare/emberOctane-vs-emberPolaris", "/compare/emberPolaris-vs-emberOctane/"], // inverse, no slash
+    ["/compare/react-vs-vue", "/compare/react-vs-vue3/"], // family alias, no slash
+    ["/compare/angular-vs-solid", "/compare/angularRenaissance-vs-solid/"], // family alias, no slash
+    ["/compare/react-vs-svelte", "/compare/svelte5-vs-react/"], // clean form of react-vs-svelte;
+  ])("301s the legacy URL %s → %s", (source, target) => {
+    expect(targetBySource.get(source)).toBe(target);
+  });
+
+  it("still covers the original inverse-with-slash redirects", () => {
+    expect(targetBySource.get("/compare/react-vs-svelte5/")).toBe("/compare/svelte5-vs-react/");
+  });
+
+  it("emits both a slashed and unslashed source for every redirect target", () => {
+    // react-vs-vue (family) should exist with and without a trailing slash.
+    expect(targetBySource.has("/compare/react-vs-vue")).toBe(true);
+    expect(targetBySource.has("/compare/react-vs-vue/")).toBe(true);
+  });
+
+  it("never redirects a canonical page onto itself (would shadow the real asset)", () => {
+    const canonicalSources = new Set(
+      canonicalPairs().flatMap(([a, b]) => [`/compare/${a}-vs-${b}/`, `/compare/${a}-vs-${b}`]),
+    );
+    for (const source of targetBySource.keys()) {
+      expect(canonicalSources.has(source)).toBe(false);
+    }
+  });
+
+  it("has no duplicate source paths", () => {
+    const sources = lines.map((l) => l.split(" ")[0]);
+    expect(new Set(sources).size).toBe(sources.length);
+  });
+
+  it("every target is a real canonical comparison page", () => {
+    const canonicalTargets = new Set(canonicalPairs().map(([a, b]) => `/compare/${a}-vs-${b}/`));
+    for (const target of targetBySource.values()) {
+      expect(canonicalTargets.has(target)).toBe(true);
+    }
+  });
+
+  it("stays well under Cloudflare's 2,100 static-redirect limit", () => {
+    expect(lines.length).toBeLessThan(2000);
+  });
+});

build/redirects.ts

@@ -0,0 +1,60 @@
+import { frameworkVersions, frameworks } from "../frameworks.ts";
+
+/**
+ * Every non-canonical URL form that should 301 to a canonical comparison page.
+ *
+ * The canonical page for a pair is `/compare/{a}-vs-{b}/`, where `a` precedes
+ * `b` in `frameworkVersions` order and both are concrete version ids. Google has
+ * historically indexed URLs that no longer match that exact shape:
+ *   - inverse order (`b-vs-a`),
+ *   - family-name aliases (`svelte`→`svelte5`, `vue`→`vue3`, `angular`→
+ *     `angularRenaissance`, `ember`→`emberPolaris`, `aurelia`→`aurelia2`),
+ *   - and any of the above without the trailing slash.
+ * Each of those 404s today because the redirect file only covered inverse pairs
+ * with a trailing slash. This enumerates the full alias × order × slash matrix so
+ * those legacy URLs 301 to the live page instead of dropping to the 404 fallback.
+ *
+ * Canonical URLs themselves are never emitted as a source: a `_redirects` rule
+ * shadows the matching static asset, so redirecting a real page would break it.
+ * The bare (no-slash) canonical form is left to Cloudflare's own 308 handling.
+ */
+export function buildRedirectLines(): string[] {
+  const versions = frameworkVersions.map((f) => f.id);
+
+  // A version id plus any family whose latest stable release is that version,
+  // e.g. svelte5 → ["svelte5", "svelte"]; react → ["react"] (family id === version id).
+  const aliasesFor = (versionId: string): string[] => {
+    const set = new Set<string>([versionId]);
+    for (const family of frameworks) {
+      if (family.latestStable === versionId) set.add(family.id);
+    }
+    return [...set];
+  };
+
+  const lines: string[] = [];
+  const seenSources = new Set<string>();
+
+  for (let i = 0; i < versions.length; i++) {
+    for (let j = i + 1; j < versions.length; j++) {
+      const a = versions[i];
+      const b = versions[j];
+      const canonicalSlug = `${a}-vs-${b}`;
+      const canonicalPath = `/compare/${canonicalSlug}/`;
+
+      for (const x of aliasesFor(a)) {
+        for (const y of aliasesFor(b)) {
+          for (const slug of [`${x}-vs-${y}`, `${y}-vs-${x}`]) {
+            if (slug === canonicalSlug) continue; // never shadow the real page
+            for (const source of [`/compare/${slug}/`, `/compare/${slug}`]) {
+              if (seenSources.has(source)) continue;
+              seenSources.add(source);
+              lines.push(`${source} ${canonicalPath} 301`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return lines;
+}