Migrating from Next.js Pages Router to App Router: The Complete Guide

The App Router is the future of Next.js. Server Components, streaming, and the new data fetching patterns deliver significant performance improvements. But migrating an existing app is non-trivial. Here's how we did it for a 200-page SaaS product without any user-facing downtime.

Pre-Migration Checklist

• Upgrade to Next.js 14+ (App Router coexists with Pages Router)
• Audit all getServerSideProps / getStaticProps usage
• List all custom _app.tsx and _document.tsx customizations
• Identify pages that use client-only APIs (window, localStorage)
• Set up parallel deployment environments for A/B comparison

Strategy: Incremental Migration

Next.js supports both routers simultaneously. This is key — you can migrate page by page without a big bang rewrite.

Phase 1: Layout Migration

Move your root layout from _app.tsx and _document.tsx to app/layout.tsx. This sets up providers, global styles, and metadata. The trickiest part is often auth providers and global state — these need to become Client Components.

Phase 2: Static Pages First

Marketing pages, docs, and other static content are the easiest to migrate. They're typically stateless and map directly to Server Components. Move these first to build confidence.

Phase 3: Data-Fetching Pages

Replace getServerSideProps with async Server Components that fetch data directly. Replace getStaticProps with generateStaticParams + async components. This is where you'll see the biggest performance wins.

Phase 4: Interactive Pages

Complex pages with forms, real-time updates, and heavy interactivity need careful splitting: Server Components for the data shell, Client Components for interactive parts.

The Gotchas

• Router.events is gone — Use usePathname() and useSearchParams() instead
• No more getInitialProps — Must refactor to Server Component fetch or client-side SWR/TanStack Query
• CSS modules scope differently — Test visual regression on every migrated page
• Third-party libs may break — Many haven't been updated for Server Components. Wrap with 'use client'

Results

• 47% smaller JavaScript bundle (Server Components ship zero JS)
• 2.1x faster Time to First Byte on data-heavy pages
• Full streaming support — Users see content progressively
• Zero downtime — Migrated over 6 weeks with no user impact

Still on Pages Router? We can plan and execute your migration.