Topic

Upgrade Next.js

Definition

A framework upgrade changes runtime and build dependencies and must be validated against migration guidance, project code, and production behavior.

In simpler words

Upgrade in small supported steps, read what changed, then let type checks and production builds prove the app still works.

Next upgrades can affect rendering, routing, caching, and dependencies, so they need a focused and evidence-based change.

Open official example (opens in new tab)

After this you can

Plan a supported upgrade path
Read official migration guidance
Validate an upgrade with project checks

Upgrade with a narrow plan

Read the official guide for the target version before editing dependencies. It identifies required codemods, renamed APIs, runtime changes, and peer dependency requirements that a version bump alone cannot explain.

Keep the upgrade focused. A framework upgrade is easier to review and roll back when it does not also introduce unrelated feature work or broad formatting changes.

An evidence-based upgrade sequence

1. Read the official guide for the target Next version
2. Update Next and required peers with pnpm
3. Apply documented migrations or codemods
4. Run pnpm typecheck and pnpm --filter @repo/web build
5. Test critical browser flows

Each step produces evidence before the release is exposed to users.

Mistake: changing major versions blindly

// Wrong
pnpm add next@latest react@latest
// merge when it compiles locally

// Right
// Follow the supported upgrade path and inspect every migration warning.

Major versions can change assumptions in routing, rendering, and dependencies.

Validate the real integration surface

Definition

A successful compile is necessary but cannot prove browser behavior, cookie handling, or product API integration.

In simpler words

Test the critical routes and flows that join Next rendering to the Nest API after the upgrade.

Inspect lockfile changes to ensure the dependency graph changed only as intended.

Record the target version, migration notes, and verification results in the upgrade PR.

Live playground

Upgrading playground

Order the upgrade steps from migration research to browser verification.

Follow the official upgrade guide; typecheck + build before merge.

next-upgrading

Keep in mind

Read the official migration guide before changing versions.
Upgrade through supported version paths and inspect the lockfile.
Run typecheck, production build, and critical authenticated browser flows.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

15 questions · concept 5 · syntax 3 · practical 4 · logic 3

1. How should you upgrade Next?

Concept

Follow the official upgrade guide/codemods for your version jumpBump the version in package.json and reinstall, nothing elseDelete node_modules and let the latest version reinstall itselfUpgrade React first, then Next will match it automatically

2. Why read breaking changes?

Syntax

Breaking changes only affect the Pages Router, not App RouterAPIs like next/navigation and caching defaults shift across majorsRelease notes list new features but never remove old APIsBreaking changes only matter if you use TypeScript

3. codemod tools?

Practical

Pin all dependencies to their latest versions automaticallyGenerate a full test suite for the upgraded codeAutomate many mechanical import/API updatesRoll back the upgrade automatically if the build fails

4. Upgrade React together?

Logic

Upgrade React only after Next has run in prod for a whileKeep React one major behind Next for stabilityReact upgrades independently and Next adapts at runtimeNext pins compatible React — upgrade as a pair per docs

5. Test plan after upgrade?

Concept

Run the dev server once and assume prod matchesTrust the codemod output and deploy without testingRun typecheck, build, and smoke critical routesRe-run only the unit tests and skip building the app

6. App Router migration from Pages?

Practical

Run a codemod that converts all pages/ files to app/ at onceDelete pages/ first, then rebuild every route in app/App and Pages can’t coexist, so migrate in one commitIncremental: move routes carefully; don’t big-bang without tests

7. Dependency peer warnings?

Syntax

Always pass --force to install past peer warningsPeer warnings are cosmetic and never affect the buildDowngrade Next until the peer warnings disappearResolve peer dependency mismatches intentionally

8. Node engine bumps?

Logic

Set engines to "*" in package.json to bypass the checkNode only matters for the build, not for next startNewer Next always supports the oldest Node LTSUpgrade Node when Next requires newer engines

9. Canary vs stable?

Concept

Canary is just stable with more logging enabledCanary releases are patched faster, so prefer them in prodStable and canary share the same version numberPrefer stable for course/prod; canary for experiments

10. Which upgrade habit is best?

Practical

Small version jumps with verification beats giant leaps in the darkWait several majors so it’s battle-tested, then leapUpgrade only patch versions and never take a majorUpgrade straight to canary to get every fix at once

11. What does a Next codemod help with?

Conceptintermediate

npx @next/codemod@latest upgrade latest

Downgrading the app if the new version breaks itBumping every dependency to its newest major at onceConverting Server Components to Client Components in bulkAutomating mechanical API/import changes during an upgrade

12. What should change when moving to the App Router?

Syntaxadvanced

// upgrading toward the App Router
import { useRouter } from 'next/router';

Replace useRouter with a useNavigation hookImport useRouter from next/navigation instead of next/routerKeep next/router but wrap it in "use client"Import useRouter from both next/navigation and next/router

13. Why upgrade React alongside Next?

Practicalintermediate

"next": "^15", "react": "^18"

Next pins compatible React versions; upgrade them togetherReact 18 is the last version Next will ever supportNext bundles its own React, so this version is ignoredReact must always be one major ahead of Next

14. What step is missing after this upgrade?

Logicadvanced

// after upgrade: no smoke test, straight to prod

Run typecheck, build, and smoke critical routes before deployingBump the version number again to trigger a fresh buildClear the CDN cache so users get the new versionRoll React back to the previous version as a safeguard

15. What is the safer upgrade habit here?

Conceptintermediate

// jumping from Next 12 to 15 in one commit, changelog unread

Smaller version jumps with verification, reading breaking changesJump straight to canary to skip the intermediate majorsUpgrade all dependencies in the same commit to save timeApply every codemod at once, then read the changelog after

Checking your session…