Migrate from Vite + React Router to Next.js

[MaxGhenis]

Supersedes #752 (evaluation issue) and builds on the RFC in #753.

Overview

Migrate policyengine-app-v2 from Vite + React Router to Next.js App Router. The current app has two entry points (website + calculator), 25 pages, 195 blog posts, 184 components, and Vercel edge middleware.

See #752 for full rationale (SEO/LLM accessibility, edge middleware complexity, no ISR, React team recommendation, Vercel-native).

Migration strategy

Approach: Separate PRs to main with Next.js and Vite running in parallel.

Phase 1 adds a next/ folder with its own Vercel project. The existing Vite app continues working untouched. Each subsequent PR migrates routes. The final PR removes Vite.

Alternatives considered

Approach	Pros	Cons
Separate PRs to main (chosen)	Small reviewable diffs, CI validates each step, easy to pause/reprioritize	Must keep both build systems working simultaneously
Feature branch with sub-PRs	Main stays stable, no parallel builds needed	Branch diverges over weeks, merge conflicts accumulate, big-bang cutover
One big PR	Simplest git workflow, clean cutover	Unreviewable diff, all-or-nothing, blocks other work
New repo, swap Vercel	Cleanest setup, no build conflicts	Two repos to maintain, shared changes need syncing, lose git history

Phases

• Phase 1: Next.js skeleton + static pages (Next.js migration: skeleton + static pages #812)
• Phase 2: Blog/research migration (Next.js migration: blog/research articles #813)
• Phase 3: Calculator app migration (Next.js migration: calculator app #814)
• Phase 4: Middleware + SEO (Next.js migration: middleware + SEO #815)
• Phase 5: External embeds + rewrites (Next.js migration: external embeds + rewrites #816)
• Phase 6: Cutover + cleanup (Next.js migration: cutover + cleanup #817)

Key decisions

• Same repo, parallel builds: Next.js in next/ folder alongside existing Vite app/
• Blog format: Convert 195 lazy-loaded TSX articles to MDX with static generation
• Dual app: Website and calculator migrate independently (already separate routers)

Current architecture

Component	Count	Migration difficulty
Static pages	~10	Easy
Blog articles	195	Medium (format conversion)
Calculator pages	6 (with nested sub-routes)	Hard
Components	184	Medium (context/router refactor)
Hooks	42	Medium
Redux slices	1 (metadata)	Easy
Contexts	~10	Medium
Vercel rewrites	6	Easy
Edge middleware	1 (complex)	Hard

[SakshiKekre]

All 6 migration phases complete:

• Phase 1 (skeleton): PR Add Next.js website workspace with skeleton pages #820 ✓
• Phase 2 (blog/research): PR Add blog article pages with SSG and markdown rendering #840, Restore Tailwind/shadcn foundation to Next.js website #875 ✓
• Phase 3 (calculator): PRs Scaffold Next.js calculator app as SPA wrapper #851, Extract listing pages from calculator catch-all to Next.js routes #861, Extract report builder routes to Next.js #862, Extract report output route from calculator catch-all to Next.js #869, Extract pathway wrappers to Next.js routes #870 ✓
• Phase 4 (middleware + SEO): SSG replaces middleware, generateMetadata on articles ✓
• Phase 5 (embeds + rewrites): All in website/next.config.ts ✓
• Phase 6 (cutover): Both domains on Next.js ✓

Remaining Vite cleanup tracked in #907. llms.txt restored in PR #905.