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
- 1Start with your lowest-traffic, simplest route as a test case before migrating core pages
- 2Ask for one route at a time rather than the whole app in a single response
- 3Keep the old Pages Router version running in parallel until you've verified the new route in production-like conditions
- 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
Related prompts
Keep going
website
Build a Next.js marketing website from scratch
A structured prompt for generating a complete multi-section marketing website in Next.js, with responsive layout, accessibility and a clear file structure.
Copy promptdebuggingDiagnose and fix a Next.js hydration mismatch error
Walks an AI through correctly diagnosing a Next.js hydration mismatch and fixing the root cause, instead of silencing it with suppressHydrationWarning.
Copy promptseoAudit and optimize a page's on-page SEO
Runs a structured on-page SEO audit of a real page and produces specific, implementable fixes rather than generic SEO advice.
Copy promptReady to put this prompt to work?
Pair it with an AI coding tool and a real project, then ship something this week.