## TL;DR This tutorial walks through migrating a real Next.js Pages Router app (`pages/`) to the App Router (`app/`) on Next.js 16.2.4[^1] in roughly forty-five minutes. You will let the two routers coexist, run the official `@next/codemod` to convert sync `params` / `searchParams` / `cookies()` / `headers()` / `draftMode()` to async[^2], move `_app.tsx` and `_document.tsx` into a single `app/layout.tsx`, port one `pages/api/*` handler to an App Router Route Handler, replace `next/router` with the three `next/navigation` hooks, and swap `getStaticPaths` for `generateStaticParams`. By the end you will have a hybrid app that ships, plus a clear path to delete `pages/` when the last route is gone. ## What you'll learn By the end you'll know how to verify your toolchain meets Next.js 16's hard floor (Node.js 20.9.0+ and TypeScript 5.1.0+)[^3], let `pages/` and `app/` coexist on the same domain so you can ship the migration one route at a time, run the `@next/codemod` recipes to mechanically rewrite the breaking changes you'd otherwise hit by hand, collapse `_app.tsx` plus `_document.tsx` into a single root layout, port a Pages Router API handler to a Route Handler with the new `NextRequest` / `NextResponse` shape and the now-async `params`, swap every `next/router` hook for the right `next/navigation` replacement, replace `getStaticProps` / `getServerSideProps` / `getStaticPaths` with their App Router equivalents, and avoid the `legacyBehavior` Link trap that breaks builds the moment you upgrade to 16.0[^4]. Verification commands at every step let you confirm the migration actually worked. ## Prerequisites Pin these versions before you start. Older releases will surface ABI and config errors that look like migration bugs but are really toolchain mismatches. - Node.js 20.9.0 or newer (Node.js 18 is no longer supported on Next.js 16)[^3]. The Node.js 22 and 24 LTS lines are both fine. - TypeScript 5.1.0 or newer[^3]; the latest stable in the 5.x or 6.x line works equally well. - npm 10+ (or a recent pnpm or yarn release) — codemod recipes are run via `npx`. - An existing Pages Router project on Next.js 14.x or 15.x. If you're on 13.x, do `npm i next@15` first and resolve type errors before chasing the App Router; mixing two major upgrades in one PR is the fastest way to lose a day. - Git working tree clean. Every codemod below mutates files; you want a single revertable commit per step. ## Step 1 — Confirm Next.js 16 is what you think it is Bump dependencies before touching any source code. The `@next/codemod` upgrade tool will edit `package.json`, `tsconfig.json`, and a handful of config files for you. ```bash # Inside the project root npx @next/codemod@latest upgrade latest ``` This is interactive — it asks which version to target (pick `latest`, which resolves to 16.2.4 as of April 15, 2026[^1]) and which package manager to use. After it exits, verify the resolved versions: ```bash node -p "require('./package.json').dependencies.next" # "16.2.4" node -p "require('./package.json').dependencies.react" # "19.2.5" — the App Router uses React 19's stable surface internally[^5] npx tsc --version # Version 5.x or 6.x — anything from 5.1.0 onward satisfies the floor ``` If `next` resolved to 15.x, the upgrade codemod silently chose conservative pinning. Force the bump explicitly: ```bash npm i next@16.2.4 react@19.2 react-dom@19.2 ``` Don't run `next dev` yet — you'll hit the async-API breaking changes before you've migrated anything. Step 2 fixes that. ## Step 2 — Apply the async Request API codemod Next.js 15 introduced async `cookies()`, `headers()`, `draftMode()`, `params`, and `searchParams` as a soft change with a synchronous compatibility shim. Next.js 16 removes the shim entirely, so any sync access throws[^2]. The codemod handles this mechanically: ```bash npx @next/codemod@latest next-async-request-api . ``` The codemod scans every TS/JS file under the current directory and rewrites four patterns: - Server Components that read `props.params` directly now `await props.params`. - Pages and Route Handlers that read `searchParams` similarly add an `await`. - Calls to `cookies()` / `headers()` / `draftMode()` from `next/headers` become `await cookies()` and friends. These three APIs are server-only — call them from Server Components, Route Handlers, or Server Actions. They are not callable from Client Components, and inside middleware you use `request.cookies` and `request.headers` on the `NextRequest` object instead[^11]. - Client Components that receive `params` or `searchParams` as props (which are now `Promise<...>`-typed) get the value unwrapped with `use()` from React: `const { slug } = use(params)`[^12]. Run a `git diff` after the codemod and skim it. The transformation is deterministic but loses a battle in two places worth fixing by hand: - Functions that destructure `params` in their signature, e.g. `function Page({ params }: { params: { slug: string } })`. The codemod usually rewrites the destructure but sometimes leaves the type annotation as the synchronous shape; update the type to `Promise<{ slug: string }>`. - Places where `params.slug` was used inside a non-async callback (a `.then()` chain, a `useMemo` dependency). You'll get a TypeScript error there until you push the `await` up to the nearest `async` boundary. After cleanup, run `npx tsc --noEmit` and fix every red squiggle the codemod missed. This is the single highest-leverage step of the whole migration; do it before adding any new App Router files so you can localize blame if something breaks. ## Step 3 — Let pages/ and app/ coexist Next.js explicitly supports running both routers in the same project, and the team has committed to long-term Pages Router support[^6]. That coexistence is what makes incremental migration safe. Create the `app/` directory at the project root (sibling of `pages/`) and add a placeholder root layout. The root layout replaces both `pages/_app.tsx` and `pages/_document.tsx` with a single file[^7]: ```tsx // app/layout.tsx import './globals.css'; import type { Metadata } from 'next'; export const metadata: Metadata = { title: 'My App', description: 'Now serving from app/ and pages/', }; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` Copy global CSS from `pages/_app.tsx` into `app/globals.css` (or whatever path the import points to). Move any `

#pages-router

Next.js Pages Router to App Router: A 2026 Migration Tutorial

Stay on the Nerd Track