Next.js Upgrade Guides

Like a few other index pages covered elsewhere in this series, the official "Upgrade Guides" page is short by design — it's a table of contents pointing at four more specific articles: Codemods, and the version-14, version-15, and version-16 upgrade guides, each covered in its own dedicated piece elsewhere in this series. This article is the orientation layer above those four: how to think about a Next.js upgrade in general, before you get into any specific version's breaking changes.

The single tool that starts every upgrade

Regardless of which version you're moving from or to, one command is the actual entry point for nearly every upgrade:

npx @next/codemod upgrade [revision]

This single command handles far more than its name suggests — it doesn't just run codemods, it also updates Next.js, React, and React DOM together, coordinated as one operation rather than three separate npm install commands you'd have to sequence correctly yourself. The revision argument is genuinely flexible: patch, minor, or major as a general category; an npm dist-tag like latest, canary, or rc; or an exact version string like 15.0.0 if you need precise control over the target. Left unspecified, it defaults to minor for stable versions — a sensible, conservative default for routine maintenance upgrades.

# The four shapes you'll use most often
npx @next/codemod upgrade patch
npx @next/codemod upgrade minor   # the default
npx @next/codemod upgrade major
npx @next/codemod upgrade 16

Worth knowing as a genuine safety behavior, not an inconvenience: if the target version you specify is the same as or older than your current version, the command simply exits without touching anything — it won't accidentally downgrade you or perform a confusing no-op that looks like it did something.

What actually happens during the upgrade

Beyond bumping version numbers in package.json, the command may prompt you to choose which specific Next.js codemods to apply, and separately whether to run the React 19 codemods if the upgrade path includes a React major version bump. This interactivity is deliberate — a codemod is a genuinely automated code transformation across your entire codebase, and confirming which ones actually apply to your specific situation before they run is a reasonable safety check rather than unnecessary friction.

That said, the tool is explicitly designed to also work well in fully non-interactive contexts. When invoked from an AI coding agent or in CI — anywhere stdin isn't a genuine TTY — it runs non-interactively and accepts every default automatically: upgrading React past 18, enabling Turbopack, applying every recommended codemod, and running the React 19 codemods where applicable. This detection is automatic; you don't need to pass anything special for it to trigger in an automated environment. If you specifically want that same non-interactive, accept-everything behavior from an ordinary interactive terminal — scripting an upgrade yourself, say — the explicit --yes (or -y) flag forces it.

# From a CI pipeline or an AI agent - runs non-interactively on its own
npx @next/codemod upgrade canary

# Forcing the same behavior from an ordinary terminal
npx @next/codemod upgrade canary --yes

--verbose is worth knowing about too, for exactly the situation where you'd want it: an upgrade that behaves unexpectedly, where seeing more detailed output about what the tool actually did (or attempted) at each step is the difference between guessing at the cause and actually diagnosing it directly.

Why codemods exist as a category, not just an upgrade detail

A codemod is a programmatic transformation applied across an entire codebase — the whole point being that a change affecting hundreds of files doesn't require a human manually opening and editing each one. Next.js provides these specifically to smooth over API changes and deprecations that would otherwise mean a tedious, error-prone manual find-and-replace across every affected file. When an API gets renamed, restructured, or deprecated between versions, there's frequently a codemod for exactly that transformation, dating all the way back to Next.js 6.

Individual codemods, run directly rather than through the bundled upgrade command, follow one consistent invocation pattern:

npx @next/codemod <transform> <path>

--dry previews the change without touching any files, and --print shows the transformed output for direct comparison — both worth running before committing to a transform on a codebase you don't have committed, reversible safety around, since some transformations touch a genuinely large number of files at once and you'll want to review the diff before it lands.

What you'll actually run for a specific upgrade

The version-specific guides in this series (14, 15, 16) go into the breaking changes each release actually introduces, and the dedicated Codemods article walks through the individual transforms available across Next.js's history in real depth — from the middleware-to-proxy rename introduced in 16.0, back through the async Dynamic APIs migration in 15.0, all the way to codemods dating from version 6. This overview's job is narrower: make sure you start any upgrade with the upgrade command itself, rather than manually chasing down individual codemods for changes you may not even know affect your specific codebase.

Key Takeaways

Question	Answer
Where every upgrade should start	npx @next/codemod upgrade [revision]
Default target if unspecified	minor, for stable versions
Runs non-interactively when	Invoked from CI or an AI agent (stdin isn't a TTY) — or explicitly via --yes
What it updates together	Next.js, React, and React DOM, as one coordinated operation
Individual codemod syntax	npx @next/codemod <transform> <path>, with --dry/--print to preview safely
Where to find version-specific breaking changes	The dedicated v14/v15/v16 guides elsewhere in this series

The practical habit worth taking from this article: don't manually chase individual API changes across a version bump — run npx @next/codemod upgrade first, let it identify and apply what's relevant automatically, and only dig into the specific version guide or individual codemod documentation for whatever it flags as needing your explicit attention.