Next.js is the framework behind many fast React websites and headless storefronts. Version 16 made its fast bundler the default, changed how caching works and renamed a core file. If your agency or in-house team built a site on Next.js 14 or 15, this release will land on your roadmap soon.
This Next.js 16 upgrade guide explains what changed, what can break and how to plan the move without surprises. Every fact comes from the official Next.js 16 announcement, which should be your reference for exact code. We write for owners and project managers as well as developers.
| Next.js 16 change | What it means |
|---|---|
| Turbopack is the default bundler | Reported 2-5x faster production builds; opt out with –webpack |
| middleware.ts becomes proxy.ts | Rename the file and the exported function |
| Async params, cookies() and headers() | Synchronous access is removed; use await |
| Minimums: Node.js 20.9, TypeScript 5.1 | Check your hosting and tooling first |
What Next.js 16 changes
The Next.js 16 announcement, published on 21 October 2025, lists these headline changes:
- Turbopack is stable and the default bundler. The team reports 2 to 5 times faster production builds and up to 10 times faster Fast Refresh. Projects with a custom webpack setup can opt out with
--webpack. - Cache Components. A new caching model built around the
"use cache"directive. Caching is entirely opt-in, and dynamic code runs at request time by default. proxy.tsreplacesmiddleware.ts. The network boundary file is renamed, and runs on the Node.js runtime.middleware.tsstill works for Edge use cases but is deprecated.- React Compiler support is stable. It is not enabled by default, because compile times rise when it is on.
- Routing improvements. Layout deduplication and incremental prefetching reduce the data transferred when links are prefetched.
- React 19.2 features such as View Transitions and
useEffectEvent. - Next.js DevTools MCP, an integration that gives AI agents context for debugging.
Version requirements
The announcement lists new minimums:
| Requirement | Next.js 16 minimum |
|---|---|
| Node.js | 20.9.0 (Node.js 18 no longer supported) |
| TypeScript | 5.1.0 |
| Browsers | Chrome 111+, Edge 111+, Firefox 111+, Safari 16.4+ |
Check your hosting too. Our guide to Node.js LTS versions explains which Node release to run, and our TypeScript 7 guide covers the compiler side.
Breaking changes to plan for
The announcement lists removals and behaviour changes. The ones most likely to affect an ordinary project:
- Async request APIs. Synchronous access to
params,searchParams,cookies(),headers()anddraftMode()is removed. You must useawait. - AMP support is removed.
next lintis removed. Use ESLint or Biome directly, andnext buildno longer runs linting.serverRuntimeConfigandpublicRuntimeConfigare removed. Use environment variables.- Image defaults changed, including a longer default cache time and a single default quality value, so image-heavy sites should re-test.
- Parallel routes need explicit
default.jsfiles, or builds fail.
Using Next.js 16 with a headless store
Many Next.js sites are the front end for a store or CMS. In that setup the framework talks to WooCommerce, Shopify or another back end through an API, so the upgrade touches data fetching and caching more than design. The new caching model is opt-in, so existing fetch behaviour does not have to change on day one, but you should still test product listings, stock levels and prices to ensure customers never see stale data.
Pay special attention to anything that reads cookies or headers, such as cart sessions and login state. Those are the places where the async request changes bite. If you are weighing this architecture for the first time, our guide to headless WooCommerce with Next.js covers the trade-offs.
A safe upgrade plan
Step 1: Upgrade in a branch
The team provides an automated codemod: npx @next/codemod@canary upgrade latest, or you can run npm install next@latest react@latest react-dom@latest. Do this on a branch, never directly on production.
Step 2: Fix the breaking changes
Work through the removals and async changes. The codemod handles many but not all cases, so read the official upgrade guide for the rest.
Step 3: Decide on Turbopack and webpack
Turbopack is the default. If a custom webpack configuration blocks you, run with --webpack first, then plan to migrate.
Step 4: Re-test the pages that matter
Test product pages, search, cart and checkout flows, plus image loading, redirects and any code that used middleware. Compare performance with your previous build.
Step 5: Roll out gradually
Deploy to a preview environment, then production during a quiet period, with a rollback ready.
Why teams upgrade, and why some wait
Reasons to upgrade soon include faster builds from Turbopack, access to the newer React features and staying inside the supported range of Node.js and TypeScript. A framework that falls several versions behind becomes harder to update, and security fixes and new libraries tend to target the latest releases.
Reasons to wait are also legitimate. A site with a heavy custom webpack setup, many third-party packages that have not confirmed support, or a major launch in the next month may prefer to schedule the upgrade after the launch. The safest posture is to decide on purpose: put the upgrade on the calendar with a date, and not let it drift until an emergency forces it.
Should you adopt Cache Components now?
Not necessarily. The announcement describes Cache Components as a new model and says caching is opt-in. Upgrading to version 16 does not force you to rewrite every page. Adopt the new caching APIs gradually where pages are slow or expensive to render, and keep the rest as they are.
Common problems to expect
The announcement points to several behaviour changes that catch teams out:
- Image handling. Local images with query strings now need
images.localPatternsconfigured, andimages.domainsis deprecated in favour ofimages.remotePatterns. Sites with many product images should re-test image loading and caching. - Separate output folders.
next devandnext buildnow use separate directories, and a lockfile stops two builds running at once in the same project. Check your scripts and CI. - Parallel routes. Every parallel route slot needs an explicit
default.js, or the build fails. - Legacy components.
next/legacy/imageis deprecated, andnext lintand AMP are gone.
None of these is hard, but together they explain why a version upgrade is a project, not a button.
Estimating the effort honestly
The effort depends on the project, so ask your developers for an estimate after a short audit rather than before. The factors that move it the most are:
- How many pages read request data such as params, cookies or headers, since each needs the async change.
- How much custom middleware exists, which should be renamed and tested.
- Image configuration, especially local images with query strings and remote domains.
- Custom webpack setup, which affects the move to Turbopack.
- Test coverage, because good tests make an upgrade faster and safer.
A small marketing site can move in an afternoon. A large store with years of custom code needs a planned sprint. Asking for the audit first keeps the quote honest.
A short testing checklist
- Home, category and product pages render correctly.
- Search, filters and pagination work.
- Cart, checkout and login flows complete.
- Images, fonts and third-party scripts load.
- Redirects, headers and any former middleware behave as before.
- Build times, page speed and error logs compared with the old version.
Upgrading from an older Next.js version
If your project is on Next.js 14 or earlier, you may be tempted to jump straight to 16. That can work, but each major version had its own breaking changes. Read the official upgrade guide for every version you skip, and run the codemods in order so changes arrive in small, reviewable steps. Many teams find it safer to move one major version at a time on a branch, run the tests, and merge before the next hop.
Also check the packages around the framework: authentication libraries, CMS clients, analytics and UI kits. Some pin an older React or Next.js range. A quick dependency audit before the upgrade shows which ones need a new release, and which are abandoned and should be replaced.
What it means for business owners
A framework upgrade does not change how your site looks, but it affects speed, security and how easy it is to hire and maintain. Ask your developers which Next.js version you use, whether your Node.js and TypeScript versions meet the minimums and when they plan to upgrade. For stores that use a headless setup, read our notes on headless WooCommerce with Next.js.
Our React development team can plan and carry out the upgrade.
Keeping upgrades routine
Teams that upgrade often find each step smaller. A good habit is to review the framework version every quarter, read the release notes and update the minor and patch versions regularly. Major versions then become a short project instead of a rescue mission. Combine this with the Node.js and TypeScript reviews described in our related guides, so the whole toolchain moves together and you never face three upgrades at once.
A note on testing and rollback
Frameworks fail in surprising places, so plan for the failure you do not expect. Keep the previous build deployable for at least a week after the upgrade, using your host’s rollback tools or a tagged container image. Run a smoke test, a short script or manual list that visits key pages and completes a test order, immediately after each deployment.
Compare error logs and page speed before and after, and ask support staff to report any customer complaints that mention pages loading oddly. If something looks wrong, roll back first and investigate afterwards. A calm rollback is a sign of a well-run upgrade, not a failure.
Planning a Next.js upgrade?
We can review your codebase against the Next.js 16 breaking changes, run the upgrade on a branch and test your key pages before release.
Frequently Asked Questions
Is Next.js 16 stable?
Yes. The official announcement of 21 October 2025 presents it as a release, with stable Turbopack and stable React Compiler support. Later patch releases have followed, so install the latest 16.x version.
Do I need to rewrite my pages to use Next.js 16?
No. Cache Components are opt-in, though you must handle the breaking changes such as async params and the proxy.ts rename if you use middleware.
What Node.js version does Next.js 16 need?
Node.js 20.9.0 or later. Node.js 18 is no longer supported.

