Upgrade Next.js

Upgrade the current project to a targeted Next.js version following official migration guides.

Instructions

1. Detect current environment:

   • Read package.json to identify the current Next.js version, React version, and package manager (npm, pnpm, yarn).
   • Read the lockfile to ensure you use the correct package manager.

2. Determine target version:

   • Do NOT blindly use @latest. Always determine the explicit target version (e.g., 15.0.0) based on user request or current LTS.
   • For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15).

3. Consult Upgrade Decision Tree:

   • Read references/decision-tree.md to find the correct codemods and checklists for your target version.

4. Security Gate:

   • You MUST request explicit user confirmation before running any codemod that modifies source files.

5. Run codemods FIRST (before installing new versions):

   • Next.js codemods should often be run against the old codebase before upgrading to automate breaking changes.
   • Example: npx @next/codemod@<target-version> <transform> <path>

6. Pin dependencies:

   • Upgrade Next.js and peer dependencies to the specific target version:
   • Example: pnpm install next@15.0.0 react@19.0.0 react-dom@19.0.0

7. Review Diff:

   • After running codemods and installing new dependencies, you MUST run git diff or review the changes.
   • Do NOT commit or ship without explicit user review of the codemod changes.

8. Test the upgrade:

   • Run npm run build (or equivalent) to check for build errors.
   • If there are errors in next.config.js or routing, resolve them manually.