iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To upgrade a Next.js 15 app to Next.js 16, first check your Node.js and TypeScript versions, then use the version-appropriate upgrade command or update the packages manually. Treat any codemod as a starting point: you still need to review async request APIs, bundler compatibility, image settings, middleware behavior, removed options, and CI checks, then build and test your own application.
Check compatibility before changing packages
The Next.js 16 upgrade guide lists these minimums and browser baselines:
- Node.js: 20.9.0 or newer. Node.js 18 is no longer supported.
- TypeScript: 5.1.0 or newer if the project uses TypeScript.
- Browsers: Chrome 111+, Edge 111+, Firefox 111+, and Safari 16.4+.
Check the version currently installed, too: the built-in next upgrade command is documented for Next.js 16.1.0 and later, while projects on earlier versions use the separate codemod command.
Choose an upgrade route
The version-specific Next.js 16 guide documents the canary codemod command. The general upgrading guide distinguishes it from the built-in command introduced for 16.1.0 and later.
#1 Best Overall
| Starting point | Command | What it does |
|---|---|---|
| Next.js versions before 16.1.0 | npx @next/codemod@canary upgrade latest |
Runs the upgrade codemod documented for earlier versions. |
| Next.js 16.1.0 or later | pnpm next upgrade |
Uses the built-in upgrade command documented for these versions. |
| Following the version 16 guide’s automated path | pnpm dlx @next/codemod@canary upgrade latest |
Runs the guide’s pnpm-based codemod command. |
| Manual package update | pnpm add next@latest react@latest react-dom@latest |
Updates the framework and React packages; TypeScript projects should also update @types/react and @types/react-dom. |
These command paths are documented for different starting versions and workflows; check your installed version before choosing. The codemod can update some common patterns, including Turbopack configuration, lint scripts, middleware naming, stabilized API prefixes, and the removed experimental PPR segment setting. Inspect its diff and make any app-specific changes yourself.
Migrate request APIs to asynchronous access
Next.js 16 removes synchronous compatibility for request-time APIs. Update code that reads cookies(), headers(), draftMode(), route params, or page searchParams to access them asynchronously, using async/await or React’s use() pattern where applicable.
Rank #2
Check more than page and layout components: route handlers and metadata-related files can also use these values. The upgrade guide calls out generated metadata image files such as opengraph-image, twitter-image, icon, and apple-icon, as well as sitemap generation, because their parameters have async changes too.
For typed routes and components, the guide recommends generated helpers including PageProps, LayoutProps, and RouteContext. Generate types with npx next typegen, then use the resulting types to catch stale synchronous assumptions.
Decide how to handle Turbopack and webpack
Next.js 16 uses Turbopack by default for both next dev and next build. If your next.config.js contains a custom webpack configuration, the default production build can fail. Check whether your app or its dependencies rely on webpack-specific behavior, then make an explicit bundler decision and test both development and production workflows. Do not assume that a successful dev server proves the production build works.
Audit next/image settings and source URLs
Several image defaults and configuration expectations change in version 16. Compare your current configuration and image URL patterns against these changes:
| Area | Next.js 16 behavior | Migration check |
|---|---|---|
| Local image query strings | Local image URLs with query strings require a matching images.localPatterns.search configuration. |
Search for local next/image sources with query strings and allow only the patterns the app needs. |
minimumCacheTTL |
The default changes from 60 seconds to 14,400 seconds (4 hours). | Set a shorter explicit value if the application depends on more frequent image revalidation. |
imageSizes |
The default size list no longer includes 16. | Add 16 explicitly if the app needs 16px optimized sources. |
qualities |
The default allowlist is [75]. Requested qualities outside the configured list are coerced to the closest allowed value. |
Configure the values your app actually requests and verify rendered images. |
| Local IP optimization | Blocked by default. | images.dangerouslyAllowLocalIP is described as dangerous; enable it only for private networks when needed. |
| Image redirects | The default maximum is three redirects instead of unlimited redirects. | Check remote image redirect chains if optimization stops working. |
| Remote image configuration | images.domains is deprecated. |
Use images.remotePatterns to specify remote image sources. |
| Legacy image component | next/legacy/image is deprecated. |
Move remaining use to next/image. |
Review middleware, proxy, and runtime requirements
The middleware convention is deprecated and renamed to proxy. Where the new convention fits, update the filename, named export, and related configuration flags. Proxy runs on Node.js, its runtime cannot be configured, and it does not support the Edge runtime. The upgrade guide advises applications that require Edge runtime to keep using middleware pending further guidance; do not rename those files without first checking their runtime needs.
Replace removed commands and configuration
Next.js 16 removes next lint, the Next config eslint option, AMP support, and the serverRuntimeConfig and publicRuntimeConfig runtime configuration options. Also, next build no longer runs linting. Make the following checks in scripts and deployment pipelines:
- Call ESLint or Biome directly rather than relying on
next lint. - Keep linting as an explicit CI step; a passing build no longer establishes that lint passed.
- Remove obsolete AMP APIs,
next/ampusage, and AMP configuration if the project still has them. - Replace removed runtime configuration with environment variables as appropriate for the app.
- If using
@next/eslint-plugin-next, check its flat-config default and migrate any remaining.eslintrcsetup as needed.
Check optional features separately from required migrations
Not every Next.js 16 change is a migration requirement. The version guide describes opting into Cache Components rather than using the removed experimental PPR flag and experimental_ppr segment setting. It also warns that PPR in version 16 differs from the version 15 canaries, so assess that change separately rather than treating it as a mechanical rename.
The guide says React Compiler support is stable but disabled by default; enabling it can increase development and build compile times because it relies on Babel. Other release features include beta Turbopack filesystem caching, an alpha Build Adapters API, enhanced routing, caching APIs including updateTag() and refined revalidateTag(), and React 19.2 features. Evaluate these on their own merits; they are not prerequisites for upgrading.
One smaller behavior change concerns scrolling: Next.js no longer overrides global smooth scrolling during SPA route transitions by default. If the prior behavior is required, the guide documents data-scroll-behavior="smooth".
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Validate the upgraded application
Documentation can identify changes to inspect, but it cannot establish which ones affect an unseen codebase or confirm that a particular migration succeeds. After applying changes, run the checks that exercise your own app:
Quick Recap
- Type-check: run the project’s TypeScript check and resolve async API and generated-type errors.
- Lint: run ESLint or Biome directly using the command configured for your repository.
- Production build: run
next buildand resolve bundler or configuration failures. - Routes and request APIs: exercise pages, layouts, handlers, metadata, and sitemaps that use request-time data.
- Images: check local query-string sources, remote redirects, requested qualities, and the cache freshness your content requires.
- Runtime-dependent behavior: verify proxy or retained middleware on the runtime your app needs.
- Navigation and prefetching: where request counts or caching matter operationally, inspect routing behavior. The guide notes layout deduplication and incremental prefetching can mean more individual prefetch requests but lower total transferred size.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
