Recipe: SEO redirect map writer

Problem

You are restructuring URL paths (e.g. /blog/old-slug → /articles/new-slug) and need a zero-regression redirect map that preserves every existing SEO signal. Manual CSV editing is error-prone and misses trailing-slash variants.

Ingredients

• A canonical source-of-truth CSV or JSON mapping old → new paths
• A Node.js script that reads the map and emits Vercel-compatible redirects
• CI step that validates no 404s are introduced
• Optional: crawl your staging deploy with a headless browser to confirm every old URL lands on the correct new page with a 200

Steps

1. Audit current URLs. Export every indexed path from Google Search Console and your sitemap. Freeze this list as the baseline.
2. Build the mapping. For each old path, determine the canonical new path. Include trailing-slash and www/non-www variants explicitly.
3. Generate redirects. Write a script that consumes the map and outputs a vercel.json redirects array with status 301 and permanent: true.
4. Validate. In CI, iterate every old URL, follow the redirect chain, and assert the final response is 200 with the expected canonical path.
5. Deploy & monitor. After shipping, watch Search Console coverage reports for 72 hours to catch any missed entries.

Pitfalls

• Redirect chains longer than one hop dilute link equity.
• Forgetting query-string preservation breaks UTM-tagged URLs.
• Using 302 instead of 301 signals temporary move to search engines.
• Not handling case-insensitive paths when your old CMS was case-insensitive.