VVersions.dev

Next.js 14 → Next.js 15

This guide covers upgrading from Next.js 14 to Next.js 15. 14 to 15 is a single, well-supported step focused on the async request APIs and caching defaults.

Version upgradeDifficulty: moderateEffort: 0.5–2 daysmedium risk

Last verified · Updated May 22, 2026

Migrating from Next.js 14 to Next.js 15. 14 to 15 is a single, well-supported step focused on the async request APIs and caching defaults.

Should you upgrade directly?

Yes. Next.js 14 → 15 is a single major step with a well-supported upgrade CLI. There is no benefit to an intermediate stop.

Key differences

  • Async request APIs: cookies/headers/draftMode/params/searchParams return Promises.
  • fetch() and GET Route Handlers are no longer cached by default.
  • React 19 in the App Router; next/font is built in.

Files and patterns to inspect

  • Pages/layouts reading `params` or `searchParams` synchronously.
  • Server code calling cookies(), headers(), or draftMode() without await.
  • fetch() calls and GET Route Handlers relying on default caching.
  • Imports of the standalone @next/font package.
  • next.config.js options deprecated between your version and 15.

Pre-migration checklist

  • Green test suite and successful next build on the current version
  • Lockfile committed; dependencies audited for React 19 / Next 15 support
  • A dedicated upgrade branch

Related paths

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.

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

Can I go straight to Next.js 15 from 14?

14 to 15 is a single, well-supported step focused on the async request APIs and caching defaults.