Skip to content
nextjs

Migrate a Next.js Pages Router app to the App Router

Directs an AI to migrate a Next.js project from the Pages Router to the App Router incrementally, one route at a time, with a rollback-safe plan.

Who should use this

Is this prompt for you?

  • Teams running an older Next.js app still on the Pages Router
  • Developers who want a safe, incremental migration rather than a risky rewrite
  • Anyone unsure how data fetching and layouts change between the two routers
The prompt

Copy this prompt

Prompt
Help me migrate part of my Next.js app from the Pages Router (pages/) to the App Router (app/).

Project context:
- Current Next.js version: [version]
- Pages currently using: [getServerSideProps / getStaticProps / getInitialProps / none]
- Routes to migrate first: [e.g. "/blog and /blog/[slug]"]
- Data fetching source: [REST API / database via ORM / CMS — name it]
- Any custom _app.tsx or _document.tsx logic I need preserved: [describe, e.g. global providers, analytics script]

Do this incrementally, not as one big rewrite:
1. Propose a migration order for my routes (simplest/lowest-risk first) and explain why
2. For the first route, show the App Router equivalent: layout.tsx, page.tsx, loading.tsx and error.tsx as needed
3. Convert the existing data fetching method to the App Router equivalent (server components, fetch with caching options, or route handlers) and explain the caching behavior difference
4. Preserve any global providers, metadata, and third-party scripts from _app/_document in the new root layout
5. Flag any client-only code (browser APIs, context providers, event handlers) that needs a "use client" boundary, and place that boundary as low in the tree as possible
6. Note any behavior differences I should test manually (e.g. loading states, error boundaries, redirects, metadata)

After each route migration, tell me what to verify manually before moving to the next route, and whether the old and new routes can coexist during the transition.

Works well with Claude Code, Cursor and OpenAI Codex.

How to use it

Getting the best result

  1. 1Start with your lowest-traffic, simplest route as a test case before migrating core pages
  2. 2Ask for one route at a time rather than the whole app in a single response
  3. 3Keep the old Pages Router version running in parallel until you've verified the new route in production-like conditions
  4. 4Pay close attention to caching behavior differences — this is the most common source of migration bugs
Expected result

What you should get back

  • A prioritized, risk-ordered migration plan across your routes
  • Working App Router files (layout, page, loading, error) for the migrated route
  • An explanation of data-fetching and caching differences versus the old approach
  • A manual verification checklist for each migrated route
Tips

Get more out of this prompt

  • Migrate route-by-route and deploy incrementally rather than attempting the whole app at once
  • Ask explicitly about caching (fetch cache, revalidate) since this is where App Router behavior differs most from Pages Router
  • Keep client component boundaries as small as possible — ask the AI to justify every "use client" it adds
Common mistakes

What to watch out for

  • Migrating everything in one pass, making it impossible to isolate what broke
  • Forgetting to move global providers and analytics scripts out of _app.tsx into the new root layout
  • Not testing caching/revalidation behavior, which behaves differently by default in the App Router

Ready to put this prompt to work?

Pair it with an AI coding tool and a real project, then ship something this week.