Next.js App Router Migration Guide

What this prompt does

This prompt casts the AI as a Next.js migration specialist guiding a [project_name] app from the Pages Router to the App Router. It inventories every route in [pages_directory], documenting each one's data-fetching method and middleware, then outputs a migration priority matrix sorted by complexity. Next it builds the App Router structure under [app_directory], mapping pages to route segments and designing layout nesting across [route_group_count] route groups. The explicit route inventory is what keeps the migration from missing edge routes.

The structure works because the App Router changes data fetching fundamentally. It converts getServerSideProps to async server components, getStaticProps to fetch with revalidation, and getStaticPaths to generateStaticParams, with exact before/after code. It then adds loading.tsx and error.tsx per segment with Suspense around [slow_component], converts pages/api routes to Route Handlers, and sets up parallel and intercepting routes for [modal_route] to preserve soft navigation and direct URL access. The [route_group_count] route groups let the AI design a layout hierarchy that maximizes shared code instead of duplicating shells across pages, and the loading.tsx plus error.tsx convention replaces the custom loading and error states the Pages Router required you to hand-roll. Converting pages/api handlers to Route Handlers shifts each endpoint to exporting explicit HTTP-method functions returning NextResponse, which is a different shape from the old default-export handler and worth getting right early.

When to use it

• You are migrating a Next.js app from Pages Router to App Router
• You want a complexity-ranked route inventory to plan the order of work
• You need exact conversions for getServerSideProps, getStaticProps, and getStaticPaths
• You want streaming via Suspense around data-heavy components
• You are converting pages/api routes to Route Handlers
• You need parallel and intercepting routes for modal patterns

Example output

The AI returns a route inventory and migration priority matrix, an App Router directory structure under [app_directory] with nested layouts across [route_group_count] route groups, exact before/after transformations for each data-fetching pattern, loading.tsx and error.tsx files per segment with Suspense around [slow_component], Route Handlers replacing pages/api with correct HTTP method exports and NextResponse, and parallel plus intercepting routes for [modal_route] enabling soft navigation with direct URL access.

Pro tips

• Start with the low-complexity routes from the priority matrix to build momentum and confidence
• The getServerSideProps-to-async-server-component conversion is what quietly breaks things — lean on the before/after mapping
• Use generateStaticParams to replace getStaticPaths; the signature and return shape differ enough to bite you
• Place loading.tsx and error.tsx per segment so streaming and error handling come almost for free
• Plan parallel and intercepting routes for [modal_route] early; modals are usually the last 10% nobody scopes
• Confirm each Route Handler exports the right method functions (GET, POST, etc.) and returns NextResponse