Migration & Upgradesadvanced
Migrate from Pages Router to App Router
✓Works with OpenClaudeYou are a Next.js migration specialist. The user wants to migrate an existing Pages Router project to the App Router architecture.
What to check first
- Run
cat package.jsonand verify Next.js version is 13.4 or higher - Check
ls -lafor existingpages/directory structure and count of route files - Run
next --versionto confirm the installed Next.js version supports App Router - Review
next.config.jsfor any custom webpack, redirects, or rewrites that need porting
Steps
- Create the
app/directory at root level alongsidepages/(both can coexist during migration) - Convert
pages/_app.tsxtoapp/layout.tsx— move global styles, providers, and context wrappers into the root layout - Convert
pages/_document.tsxtoapp/layout.tsx— merge<html>,<head>, and<body>structure using the RootLayout component - Migrate route files: convert
pages/blog/[id].tsxtoapp/blog/[id]/page.tsx(nested folder +page.tsxfile) - Convert API routes: move
pages/api/users.tstoapp/api/users/route.tsand refactor handlers to useNextRequest/NextResponse - Update dynamic routes using
getStaticProps/getServerSideProps— replace with Server Components orgenerateStaticParams()for static generation - Port middleware: move
middleware.tsfrom project root toapp/middleware.tsand update matcher patterns if needed - Remove pages directory entirely and verify all routes resolve using
npm run devand test each migrated endpoint
Code
// Step 1: Convert pages/_app.tsx to app/layout.tsx
import type { ReactNode } from 'react'
import './globals.css'
export const metadata = {
title: 'My App',
description: 'Generated by Next.js',
}
export default function RootLayout({
children,
}: {
children: ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
// Step 2: Convert pages/blog/[id].tsx to app/blog/[id]/page.tsx
import { notFound } from 'next/navigation'
interface PageProps {
params: Promise<{ id: string }>
}
export async function generateStaticParams() {
const posts = await fetch('https://api.example.com/posts')
.then((res) => res.json())
return posts.map((post: { id: string }) => ({
id: post.id,
}))
}
export default async function BlogPage({ params }: PageProps) {
const { id } = await params
const post = await fetch(`https://api.example.com/
Note: this example was truncated in the source. See the GitHub repo for the latest full version.
Common Pitfalls
- Treating this skill as a one-shot solution — most workflows need iteration and verification
- Skipping the verification steps — you don't know it worked until you measure
- Applying this skill without understanding the underlying problem — read the related docs first
When NOT to Use This Skill
- When a simpler manual approach would take less than 10 minutes
- On critical production systems without testing in staging first
- When you don't have permission or authorization to make these changes
How to Verify It Worked
- Run the verification steps documented above
- Compare the output against your expected baseline
- Check logs for any warnings or errors — silent failures are the worst kind
Production Considerations
- Test in staging before deploying to production
- Have a rollback plan — every change should be reversible
- Monitor the affected systems for at least 24 hours after the change
Related Migration & Upgrades Skills
Other Claude Code skills in the same category — free to download.
Migration & Upgradesintermediate
Node Upgrade
Upgrade Node.js version with compatibility fixes
Migration & Upgradesintermediate
React Upgrade
Upgrade React to latest version
Migration & Upgradesintermediate
TypeScript Migration
Migrate JavaScript project to TypeScript
Migration & Upgradesintermediate
Jest to Vitest
Migrate from Jest to Vitest
Migration & Upgradesintermediate
CJS to ESM
Convert CommonJS to ES Modules
Migration & Upgradesintermediate
Webpack to Vite
Migrate from Webpack to Vite
Migration & Upgradesadvanced
Database Migration
Migrate between databases
Want a Migration & Upgrades skill personalized to YOUR project?
This is a generic skill that works for everyone. Our AI can generate one tailored to your exact tech stack, naming conventions, folder structure, and coding patterns — with 3x more detail.