RFC: Standardize on Next.js + Tailwind + shadcn/ui as the default stack for all PolicyEngine frontend projects

[MaxGhenis]

Proposal

Adopt Next.js (App Router) + Tailwind CSS v4 + shadcn/ui as the default frontend stack for all PolicyEngine projects — the main app, interactive tools, calculators, and dashboards.

This supersedes #752 (which proposed Next.js for the main app only).

Why now

1. The Tailwind + shadcn/ui migration is done (Migrate from Mantine to Tailwind CSS v4 + shadcn/ui #730) — the component layer is already framework-agnostic
2. We're building workarounds for missing framework capabilities — the prerender PR (Pre-render blog posts for LLM and search engine accessibility #751) reimplements what Next.js provides natively (SSG/SSR for blog posts, OG tags, LLM accessibility)
3. Our tools are leveling up — standalone calculators are growing into multi-page apps with content, SEO needs, and real routing. Starting on Vite means migrating each tool later or building per-tool SSR workarounds.
4. The React team recommends Next.js as the first framework for new projects, describing it as taking "full advantage of React's architecture to enable full-stack React apps"

Decision analysis

We ran a structured forecast (farness decision 36f0291e) with these KPIs weighted by importance:

KPI	Weight	Description
Things just work	2.0x	% of features that work without workarounds (SSR, SEO, OG tags, LLM access)
Dev velocity	1.5x	Hours for CC to ship a typical feature
Workaround burden	1.5x	Hours/quarter maintaining framework workarounds
Colleague clarity	1.5x	How clear is the stack to new contributors/CC sessions (1-10)
Bug surface	1.0x	Framework-related bugs per quarter

Results (assuming tools level up over time):

Option	Works	Velocity	Workarounds	Bugs	Clarity	Score
Stay on Vite	55%	3h	45h/q	3/q	4/10	318
Next.js (main app only)	90%	2.5h	15h/q	4/q	9/10	510
Next.js (everything)	92%	2.5h	3h/q	6/q	9/10	522
Wait 6 months	60%	3h	35h/q	3/q	4/10	342

Key drivers:

• "Things just work" jumps from 55% → 92%. Blog posts, OG tags, LLM accessibility, sitemaps, API routes — all built in. No custom prerender scripts, no edge middleware bot detection, no per-tool SSR workarounds.
• Workaround burden drops from 45h/quarter → 3h/quarter. Every current workaround (prerender, llms.txt, OG middleware, Modal proxy) either becomes unnecessary or trivial.
• Colleague clarity jumps from 4/10 → 9/10. "It's a Next.js app" is a complete mental model. No need to explain the workaround layer.
• Bug surface increases slightly (6 vs 3/quarter) due to server/client component boundary — but these are loud build-time errors, not silent production failures like the workaround bugs.

What this means in practice

Default stack for all new projects

• Next.js App Router (not Pages Router)
• Tailwind CSS v4 with tw: prefix
• shadcn/ui (radix primitives)
• TypeScript
• Deployed on Vercel

Migration plan

Phase 1 — Main app (policyengine-app-v2):

1. Set up Next.js App Router alongside existing Vite build
2. Migrate content routes first (blog, research, team, model docs) — these benefit most from SSG
3. Migrate calculator/household builder as client components ("use client")
4. Remove Vite, react-router-dom, prerender workarounds, custom middleware

Phase 2 — New tools:

• All new interactive tools start from a Next.js + Tailwind + shadcn template
• Template includes "use client" on the main page by default (acts like a Vite SPA until you need SSR)

Phase 3 — Existing tools (incremental):

• Migrate tools as they level up or need significant changes
• No need to migrate stable, single-page calculators that aren't changing

What carries over unchanged

• All Tailwind styles and shadcn/ui components (framework-agnostic)
• Redux stores and interactive logic (wrapped in "use client")
• Vercel deployment (first-class Next.js support)
• All existing test infrastructure

Risks and mitigations

Risk	Mitigation
Server/client component boundary bugs in AI-generated code	CLAUDE.md template with explicit RSC patterns; default to "use client" for interactive pages
Next.js breaking changes between versions	Pin versions, update quarterly
Vercel lock-in	Next.js runs on any Node.js host; Vercel is best but not required
Migration disruption to main app	Incremental migration — content routes first, calculator last
Slower builds than Vite for simple tools	Acceptable tradeoff (10-30s vs 2-5s) given the benefits

Not proposing

• Migrating stable, unchanged tools that don't need new features
• Switching away from React
• Any backend changes

[anth-volk]

Strongly agree on the benefits of doing so, particularly Next.js

[MaxGhenis]

Blog/report workflow: MDX in Next.js

As part of this migration, we should also move our blog/report pipeline to MDX. This is a natural fit with Next.js and solves several current pain points.

Current state

• 195 articles (180 markdown, 15 Jupyter notebooks)
• 19 posts embed Plotly charts via fenced plotly code blocks
• 33 posts embed iframes (mostly PolicyEngine calculators)
• Build-time scripts generate llms.txt, llms-full.txt, pre-rendered HTML, and sitemap
• Custom markdown rendering pipeline with special handling for Plotly JSON, iframes, table of contents, etc.

Recommendation: MDX + Recharts

MDX is markdown that supports JSX — meaning authors write normal markdown but can embed React components inline. Next.js has first-class MDX support via @next/mdx.

Why MDX fits us well:

• Backwards-compatible — existing .md files work as-is with zero changes
• Plotly → Recharts — replace all Plotly charts with Recharts, which is already our standard in the app. Recharts is React-native (no heavy Plotly.js bundle), uses our design tokens, and renders as SVG (great for SSG). The 19 posts with fenced plotly JSON blocks become <PolicyEngineChart /> components using Recharts under the hood.
• Interactive embeds become components — instead of raw iframes, use <PolicyEngineCalculator country="us" reform="..." /> with proper loading states
• Static generation built-in — Next.js pre-renders MDX at build time, so LLMs and search engines get full HTML without the middleware workaround from PR Pre-render blog posts for LLM and search engine accessibility #751
• Frontmatter support — via gray-matter, same as current posts.json metadata but co-located with content
• Syntax highlighting — via rehype-pretty-code or shiki, better than current approach

Migration strategy

1. New posts: Write in MDX from day one, use Recharts for all charts
2. Existing markdown: Works unchanged — MDX is a superset of markdown
3. Plotly → Recharts (19 posts): Convert fenced Plotly JSON blocks to <PolicyEngineChart /> Recharts components. This also drops the ~3MB Plotly.js dependency from the blog bundle.
4. Iframe posts (33): Convert to <Embed /> components when posts are updated
5. Jupyter notebooks (15): Keep the existing notebook renderer or convert to MDX when updated

This is incremental — no big-bang migration needed. The shared component library (shadcn/ui + custom PolicyEngine components) means charts, calculators, and other embeds are consistent across all posts.