Next.js Migration Auto

Automate Next.js migration from Pages Router to App Router with file structure analysis, automatic route conversion, layout generation, and migration complexity scoring.

When to Use This Command

Run this command when you need to migrate a Next.js application from the Pages Router to the App Router architecture.

• You have an existing Pages Router application and want to adopt the App Router
• You need to assess migration complexity before committing to the work
• You want automated conversion of _app.tsx, _document.tsx, and page files to App Router equivalents
• You need to migrate API routes from pages/api/ to app/api/ with the new route handler format

Use it also when:

• You want a hybrid migration strategy that runs both routers simultaneously
• You need to update data fetching from getServerSideProps / getStaticProps to Server Components

Quick Start

Copy
# .claude/commands/nextjs-migration-auto.md
name: nextjs-migration-auto
description: Migrate Next.js from Pages Router to App Router
arguments:
  mode: analyze | migrate | hybrid

Copy
# Analyze migration complexity first
claude nextjs-migration-auto "analyze"

Expected output:
Migration Analysis:
  Current: Pages Router (Next.js 13.4.1)
  Pages: 24 files in pages/
  API Routes: 8 files in pages/api/
  Custom _app: Yes (providers, global state)
  Custom _document: Yes (fonts, meta tags)
  Complexity Score: 6/10

Estimated Effort:
  Automated: 18 files (75%)
  Manual Review: 6 files (25%)
  Risk Areas: _app.tsx providers, getServerSideProps

Core Concepts

Concept	Description
Pages Router	Legacy routing via pages/ directory with getServerSideProps
App Router	Modern routing via app/ directory with Server Components
Layout	Shared UI wrapper replacing _app.tsx in the App Router
Route Handler	App Router API routes using export async function GET() syntax
Complexity Score	1-10 rating based on file count, custom features, and data fetching

Migration Path:
  pages/_app.tsx ─────────> app/layout.tsx
  pages/_document.tsx ────> app/layout.tsx (head elements)
  pages/index.tsx ────────> app/page.tsx
  pages/about.tsx ────────> app/about/page.tsx
  pages/api/users.ts ────> app/api/users/route.ts
  getServerSideProps ────> Server Component (direct fetch)
  getStaticProps ────────> generateStaticParams + fetch

Configuration

Parameter	Default	Description
mode	analyze	Operation mode: analyze, migrate, hybrid
target-version	latest	Target Next.js version for migration
include-api	true	Migrate API routes alongside pages
preserve-pages	false	Keep original pages/ files during migration
dry-run	false	Generate migration plan without making changes

Best Practices

1. Always run analyze first -- Understand the migration complexity and effort estimate before starting. Address risk areas identified in the analysis.

2. Migrate incrementally with hybrid mode -- Use hybrid mode to run both routers simultaneously, migrating one route at a time rather than all at once.

3. Start with leaf pages, not layouts -- Migrate simple pages without shared state first, then tackle _app.tsx and layout-heavy pages once you are comfortable.

4. Update data fetching patterns -- Replace getServerSideProps with direct fetch() in Server Components. Replace getStaticProps with generateStaticParams.

5. Test each migrated route individually -- After migrating a route, verify it works in both development and production builds before moving to the next one.

Common Issues

1. Client-side state in _app.tsx -- Context providers and global state in _app.tsx must be wrapped in a Client Component and placed in the root layout.tsx.

2. Dynamic routes syntax change -- Pages Router [id].tsx becomes [id]/page.tsx in the App Router. Ensure all dynamic segments are migrated to directory-based routing.

3. getServerSideProps not available in App Router -- App Router does not support getServerSideProps. Data fetching happens directly in Server Components using fetch() with caching options.