Scaffold Next.js calculator app as SPA wrapper

[SakshiKekre]

Summary

Scaffolds a Next.js app (calculator-app/) that wraps the existing Vite calculator as a client-side SPA, and adds router abstraction infrastructure for incremental route extraction. Follows the official Next.js Vite migration guide.

SPA wrapper

• [[...slug]] catch-all route imports CalculatorApp with ssr: false
• import.meta.env polyfilled via webpack DefinePlugin
• generateStaticParams prerenders the index route
• Shared CSS/Tailwind imported from app/src/app.css
• Public assets symlinked from app/public/

Router abstraction (for incremental route extraction)

• CountryContext — decouples useCurrentCountry() from react-router's useParams
• NavigationContext — useAppNavigate() with push/replace/back, works in both routers
• LocationContext — useAppLocation()/useAppPathname() for pathname and search
• AppLink — drop-in replacement for react-router's Link component
• All contexts wired into CountryGuard (react-router) and [countryId]/layout.tsx (Next.js)
• Existing tests updated to provide CountryProvider in test wrappers

CI

• Calculator typecheck and build steps added to pr.yaml

Dependent PRs and merge strategy

main
  └── #851 (this PR)
        ├── #861 (listing pages)
        ├── #862 (report builder)
        │     └── #869 (report output)
        └── #870 (pathway wrappers)

Merge order: leaves first, then merge up into this PR, then merge to main.

1. Merge Extract report output route from calculator catch-all to Next.js #869 → Extract report builder routes to Next.js #862
2. Merge Extract listing pages from calculator catch-all to Next.js routes #861, Extract report builder routes to Next.js #862, Extract pathway wrappers to Next.js routes #870 → this PR (nextjs-calculator-migration)
3. Merge this PR → main

This avoids rebasing each PR onto main individually. The PRs are tightly coupled (all part of the same migration, all depend on the same infra), so merging them as a single unit makes sense. Each sub-PR is reviewed individually; this PR is the integration point.

Going live checklist

Before going live

1. Create Vercel project for calculator-app/ (separate from existing policyengine-calculator)
2. Configure env vars on new Vercel project: NEXT_PUBLIC_WEBSITE_URL, NEXT_PUBLIC_CALCULATOR_URL, NEXT_PUBLIC_IPAPI_CO_KEY
3. Set Ignored Build Step so only changes to calculator-app/, app/src/, packages/design-system/ trigger rebuilds
4. Verify all routes work on the Vercel preview deployment with catch-all removed

Going live

5. Point app.policyengine.org domain to the new Vercel project

Immediately after going live

6. Remove the catch-all — delete calculator-app/src/app/[[...slug]]/ (page.tsx + client.tsx). This is dead code once all routes are extracted and removes the entire Vite bundle from the Next.js app
7. Monitor for any route 404s or broken flows before decommissioning Vite

After Vite decommission (later)

8. Remove bridge wrappers from CalculatorRouter.tsx (ModifyReportPageRoute, ReportOutputRoute)
9. Remove react-router-dom dependency
10. Remove CalculatorRouter.tsx and CalculatorApp.tsx
11. Remove Vite config, scripts, and app/src/main.calculator.tsx
12. Consider consolidating app/src/ into calculator-app/src/

Multi-zones (future, independent of Vite decommission)

Once website, model explorer, and API docs are all on Next.js, enable multi-zones to share a single domain (policyengine.org) with seamless client-side navigation. Currently these are separate Vercel projects served via rewrites, causing full page reloads when users click between Model, API, and other apps in the header. Multi-zones would eliminate that. Ref: #755

Dev workflow changes

Before this PR merges

• cd app && bun run dev:calculator — runs Vite calculator on port 3001

After this PR merges (during migration)

• cd app && bun run dev:calculator — Vite calculator still works (port 3001)
• cd calculator-app && bun run dev — Next.js calculator (same port, run one at a time)
• Both should behave identically for testing

After going live

• cd calculator-app && bun run dev — primary dev server
• Vite dev server still available for comparison/debugging until decommissioned

Test plan

• cd calculator-app && bun run dev — loads full calculator at localhost:3001
• Navigate between Reports, Simulations, Policies, Populations via sidebar
• Country switching works (US, UK)
• cd app && VITE_APP_MODE=calculator npx vite — Vite dev server still works
• bun run test — all 2950 tests pass
• bun run lint — no errors
• bun run typecheck — passes

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
policyengine-app-v2	Ready	Preview, Comment	Mar 25, 2026 9:46pm
policyengine-calculator	Ready	Preview, Comment	Mar 25, 2026 9:46pm
policyengine-website	Ready	Preview, Comment	Mar 25, 2026 9:46pm

[anth-volk]

Migration gap: [countryId]/layout.tsx doesn't sync Redux metadata.currentCountry

CountryGuard (the react-router side) dispatches setCurrentCountry(countryId) to Redux on every country change (CountryGuard.tsx:27-31). The Next.js [countryId]/layout.tsx only provides context — it never dispatches to Redux.

This is fine for Phase 1 (the catch-all still routes everything through CountryGuard), but it will become a bug in Phase 2 when routes are extracted to Next.js pages. Two production components read metadata.currentCountry directly from Redux instead of using context:

• MultiYearValueSelector.tsx:17 — uses it for country-specific max years (US: 10, UK: 5)
• MultiYearValueSelectorV6.tsx:22 — same logic

Suggested fix (can be a follow-up): Migrate both components from useSelector((state) => state.metadata.currentCountry) to useCurrentCountry(). This is a ~6-line diff, requires no new infrastructure, and makes the comment at metadataReducer.ts:118 ("only used internally by useFetchMetadata") accurate.