Upgrade to Next.js 15

Next.js 15 is a recommended upgrade for apps on 13 or 14. The risk concentrates in the now-async request APIs (cookies, headers, params, searchParams) and the changed caching defaults — not in rewriting your routes.

Version upgradeDifficulty: moderateEffort: 0.5–3 days for a typical appmedium risk

Last verified May 20, 2026 · Updated May 22, 2026

Next.js 15 is a recommended upgrade for apps already on 13 or 14. Most breakage comes from the now-async request APIs and the changed caching defaults — the official @next/codemod upgrade CLI handles most of the mechanical work. Budget half a day to three days depending on how much you read cookies/headers/params synchronously.

Who should upgrade

Apps on 13/14 wanting React 19 support in the App Router and the latest caching control.
Teams that want the simpler async request-API model and built-in next/font.
Anyone blocked by bugs fixed in the 15.x line.

Who should wait

Apps with a critical dependency that has no React 19-compatible release (App Router only).
Apps mid-migration from Pages Router to App Router — finish or stage that first.

What changed

Request APIs are async: cookies(), headers(), draftMode(), params, and searchParams now return Promises.
Caching defaults: fetch() and GET Route Handlers are no longer cached by default; opt in with cache: 'force-cache'.
React 19 support in the App Router (Pages Router stays on React 18).
next/font is built in; the standalone @next/font package is removed.
The @next/codemod upgrade CLI automates the version bump and async-API rewrites.

The risk is async request APIs and caching, not routing

The upgrade rarely rewrites your route structure. It touches every place you read cookies(), headers(), params, or searchParams synchronously, plus any fetch/Route Handler that relied on the old caching default. Inspect for those first.

Recommended upgrade path

Fast path for apps already on 13 or 14

# 1. Run the official upgrade CLI (bumps deps + applies codemods)$ npx @next/codemod@canary upgrade latest# 2. Typecheck + build$ npx tsc --noEmit && npm run build

Compatibility matrix

Concern	Next.js 14	Next.js 15
cookies() / headers()	Synchronous	Async (returns a Promise)
params / searchParams	Plain object	Promise — must be awaited
fetch() caching	Cached by default	Not cached by default
GET Route Handlers	Cached by default	Not cached by default
React (App Router)	React 18	React 19
next/font	@next/font package	Built in (package removed)

Migration executionAI-assisted migration workflow

Upgrade this app to Next.js 15. First inspect for synchronous request-API access (cookies, headers, draftMode, params, searchParams) and for fetch/Route Handlers relying on the old caching default. Then run `npx @next/codemod@canary upgrade latest`, await the async request APIs, set explicit caching where the old default was relied on, and resolve type errors. Run typecheck, lint, build, and tests after each step and report before continuing.

Safety: Incremental edits only. Pause for review after the codemod and after each caching decision.

PR review checklist

next, react, and react-dom are on compatible versions
cookies(), headers(), draftMode() are awaited everywhere
params and searchParams are awaited in pages, layouts, and routes
Caching is explicit where the old fetch/Route Handler default was relied on
No standalone @next/font imports remain
next build succeeds with no new sync-access errors

Rollback strategy

Keep the dependency bump, codemod, and manual fixes in separate commits.
Revert to the prior next/react/react-dom versions and reinstall if a blocking incompatibility appears.
Hold the upgrade behind a release branch until the full test suite and next build are green.

Common errors

'cookies() should be awaited' / 'searchParams should be awaited' — await the async request API.
Pages unexpectedly going dynamic — set cache: 'force-cache' or dynamic config to restore static behavior.
Module not found '@next/font' — switch to the built-in next/font import.

Official sources

Official docsNext.js 15nextjs.orgreliability 98%
Backs the breaking-change and migration-step claims.
Migration guideUpgrading: Version 15nextjs.orgreliability 98%
Backs the breaking-change and migration-step claims.
GitHub releaseNext.js releasesvercel/next.jsreliability 92%
Backs the breaking-change and migration-step claims.

Copy-ready AI prompts

Structured prompts for an AI coding assistant. Inspect first, then execute incrementally, and keep a human in the review loop.

Repo inspectionRepo inspection prompt

You are helping migrate a Next.js codebase from nextjs-14 to nextjs-15.

Do not edit files yet. First inspect the repository and report:
1. The exact next, react, and react-dom versions in package.json and the lockfile.
2. Whether the app uses the App Router (app/), the Pages Router (pages/), or both.
3. Synchronous usage of cookies(), headers(), draftMode(), and any page/layout/route that reads params or searchParams synchronously.
4. fetch() calls and GET Route Handlers that rely on the old default caching behavior.
5. Usage of the standalone @next/font package and any next.config edits that may break.
6. The build, lint, and test commands.

Return: a migration risk summary, the files most likely to break, a suggested migration order, the commands to run before editing, and any questions that need human confirmation.

Safety: Inspection only. The agent must not modify files in this step.

Works with Claude Code, Cursor, GitHub Copilot

Migration executionMigration execution prompt

Migrate this codebase from nextjs-14 to nextjs-15, one concern at a time.

Work in this order and pause for review after each: (1) bump next, react, and react-dom, (2) run the official upgrade CLI (npx @next/codemod@canary upgrade latest), (3) await the now-async request APIs (cookies/headers/draftMode/params/searchParams) flagged during inspection, (4) decide caching intent per fetch/Route Handler and add cache: 'force-cache' or dynamic config where the old default was relied on, (5) fix type errors.

After each step run the project's typecheck, lint, build, and tests, and report results before continuing. Do not refactor unrelated code.

Safety: Apply changes incrementally and keep each step reviewable. Never bundle unrelated refactors.

Works with Claude Code, Cursor, GitHub Copilot

Test plan

Commands

npx tsc --noEmit
npm run lint
npm test -- --watch=false
npm run build

Manual checks

Dynamic routes: load pages reading params/searchParams and confirm no 'sync access' runtime errors.
Auth/session: exercise routes using cookies() and headers() after awaiting them.
Caching: verify pages and Route Handlers that should stay static still serve cached output.

Regression risks

Pages silently going dynamic because the old fetch caching default was relied on.
Synchronous request-API access throwing only on specific routes at runtime.
Third-party packages not yet compatible with React 19 in the App Router.

Acceptance criteria

Typecheck, lint, tests, and next build all pass.
No synchronous request-API warnings or errors in build/runtime logs.
Caching behavior is explicit and matches the intended static/dynamic boundaries.

Frequently asked questions

Is Next.js 15 a hard upgrade?

For most 13/14 apps it is moderate — the @next/codemod upgrade CLI handles the dependency bump and the async request-API rewrites. The effort scales with how much you read cookies/headers/params synchronously and how much you depended on the old caching defaults.

Do I have to change my caching code?

Only where you relied on the old defaults. fetch() and GET Route Handlers are no longer cached by default, so anything that should stay static needs explicit opt-in via cache: 'force-cache' or a dynamic/static route config.