How to upgrade your Next.js version: codemods and a safe rollout

Before you start

Write down your current versions of Next.js, React and Node.js; whether you use the App Router, the Pages Router or both; any custom webpack configuration; your middleware; and where the application is deployed. Make sure the end-to-end tests run, and that you can create a preview deployment of a branch.

Step 1: Upgrade Node.js first

Next.js 16 needs Node.js 20.9 or later, but Node.js 20 itself stopped receiving security fixes on 30 April 2026. Move to a line that is still supported: 22 (security fixes until 30 April 2027), 24 (until 30 April 2028) or 26 (until 30 April 2029). Ship the Node.js upgrade on its own, before touching Next.js.

Step 2: One major version at a time

Go from 13 to 14, 14 to 15 and 15 to 16 in separate steps, each with its own branch, tests and deploy. Jumping several versions at once mixes breaking changes together and makes every failure harder to explain. The Next.js documentation has a guide for each version.

Step 3: Run the codemods

From Next.js 16.1, npx next upgrade upgrades to the latest version. On earlier versions, use the codemod package instead:

npx @next/codemod@canary upgrade latest

The upgrade codemod does not run every migration. If the code still reads request data synchronously, also run:

npx @next/codemod@canary next-async-request-api .

Read every change the codemods make, and resolve any comments they leave in the code; a green build is not proof that the behaviour is unchanged.

What changed in Next.js 15

• React 19 became the minimum version.
• cookies(), headers(), draftMode(), params and searchParams became asynchronous, with temporary synchronous access.
• fetch requests and GET route handlers are no longer cached by default.
• Page segments are no longer reused from the client-side cache on navigation unless configured.
• The @next/font package was removed in favour of next/font, and geo and ip were removed from NextRequest.

What changed in Next.js 16

• Node.js 20.9 and TypeScript 5.1 are the minimums.
• Turbopack is the default for next dev and next build; a custom webpack configuration makes the build fail unless you pass --webpack or migrate the configuration.
• Synchronous access to request data is removed entirely.
• middleware is renamed proxy and runs on Node.js only; edge middleware should not be renamed blindly.
• next lint, runtime configuration (serverRuntimeConfig, publicRuntimeConfig) and AMP support are removed.
• Image defaults changed: a 4-hour minimum cache time, a single default quality, local images with query strings need configuration, and redirects are limited.
• Parallel route slots need an explicit default.js, and revalidateTag needs a cache-life profile as its second argument.

Step 4: Test what the codemods cannot

• Data freshness: caching defaults changed in both versions, so check every page that shows data that changes.
• Sign-in and redirects in middleware or proxy.
• Images: sizes, qualities and any images loaded through query strings or redirects.
• Search basics: titles, descriptions, canonical tags, the sitemap and structured data on the main templates.
• Speed: compare Core Web Vitals and Lighthouse scores before and after.

Leave new options such as the React Compiler and Cache Components switched off during the upgrade; the Next.js documentation itself says not to enable them merely to complete one. Adopt them later, as separate changes.

Step 5: Roll out safely

Deploy the branch to a preview environment and run the end-to-end tests against it. Release to production at a quiet time with the previous deployment ready to restore in one step, then watch errors and Core Web Vitals for a few days before starting the next major version.

Questions people ask

1. 01

   Can we skip a version?

   It is possible, but each version's changes still apply, and the codemods are written per version. Separate steps are safer and usually faster overall.

2. 02

   Do we have to move to the App Router?

   No. Upgrading Next.js and moving from the Pages Router to the App Router are separate projects; do them separately.

3. 03

   How long does an upgrade take?

   It depends on the number of routes, the custom configuration, the libraries involved and the tests you have. The breaking-change lists above are the best early estimate of the work.