Next.js App Router Upgrade

Point this agent at a Next.js app that uses the Pages Router and ask it to plan the upgrade. It inventories every route under pages/, plans an incremental adoption where pages/ and app/ coexist, converts routes leaf-first, and proves parity by building both trees and comparing route manifests. No env vars are required — everything runs against your local repository.

What it does

1. Map the Pages Router surface: every route, its data fetching (getServerSideProps / getStaticProps / getInitialProps), _app/_document customizations, API routes, middleware, and next/router hook usage — each route tiered mechanical / rework / redesign.
2. Plan an incremental upgrade: shared-layout extraction, leaf-first route order, and per-route risk so pages/ and app/ coexist safely for the whole migration.
3. Convert routes: layout.tsx/page.tsx structure, data fetching to async Server Components and generateStaticParams, next/head to metadata exports, next/router to next/navigation, and explicit client/server component boundaries.
4. Validate parity — run next build with both trees, compare route manifests, and walk a per-route render checklist; report PASS/PARTIAL/FAIL with the route table as evidence.

Prerequisites

None required. Optionally:

• VERCEL_TOKEN — enables preview deploys of the converted app for parity checks on real infrastructure.

Current scope

This solution migrates routes, layouts, data fetching, metadata, and router-hook usage inside one Next.js app. It does not upgrade the Next.js version itself (run the official codemods/upgrade first if needed), does not redesign getInitialProps data flows for you (it flags them with options), does not migrate custom servers, and does not rewrite third-party libraries that only support the Pages Router.