How do you migrate from the Pages Router to the App Router in Next.js?

Q: How do you migrate from the Pages Router to the App Router in Next.js?

**Target Audience:** Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. **Difficulty:** Hard > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:`. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the **Verified** section, against real output from a build or a running server; each Verified block says which version it ran on. ## 1. Why This Even Matters — A Story First Migrating is like moving a library to a new building while it stays open. You move one section at a time. A reader walking from a moved section to an unmoved one has to cross the street (a full page load), so you move sections that are often read together at the same time, and you keep signs (redirects and shared layouts) consistent in both buildings. ## 2. The Core Idea 📌 **Interview term: Incremental adoption** — ru

The problem

Question presented to candidate: "We have a large Pages Router app. How would you plan the migration to the App Router without a big-bang rewrite?"

What a strong answer should cover:

Both routers work in one app, so migrate incrementally, route by route; a path must not exist in both.
Start with the root layout (app/layout.tsx replaces _app and _document), then move low-risk pages.
Replace data functions with Server Component fetching, next/router with next/navigation hooks, next/head with the Metadata API, and API routes with Route Handlers when convenient.
Navigation between the two routers is a hard navigation (full page load) and Link does not prefetch across them, so migrate related sections together.
Use codemods for mechanical changes and upgrade Next.js first so both routers run on the same version.

Clarifying questions expected:

"Which sections are most self-contained?" — they migrate first.
"Which libraries rely on next/router or _app providers?" — they need Client Component wrappers.

Code / implementation expected: Yes — a root layout replacing _app and _document, and a page conversion.

nextjs
migration
app-router
pages-router

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. Difficulty: Hard

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term:. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the Verified section, against real output from a build or a running server; each Verified block says which version it ran on.

1. Why This Even Matters — A Story First

Migrating is like moving a library to a new building while it stays open. You move one section at a time. A reader walking from a moved section to an unmoved one has to cross the street (a full page load), so you move sections that are often read together at the same time, and you keep signs (redirects and shared layouts)

The solution is hidden so you can try first

4 min read · 8 sections

Read the code

A root layout replacing _app and _document

// app/layout.tsx (replaces pages/_app.tsx and pages/_document.tsx)
import type { Metadata } from "next";
import { Providers } from "./providers";
import "./globals.css";

export const metadata: Metadata = { title: { template: "%s | Shop", default: "Shop" } };

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

// app/providers.tsx
"use client";
import { ThemeProvider } from "@/lib/theme";
export function Providers({ children }: { children: React.ReactNode }) {
  return <ThemeProvider>{children}</ThemeProvider>;
}

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.