| name | next-upgrade |
| user-invocable | true |
| description | Upgrade Next.js to the latest version following official migration guides and codemods |
| allowed-tools | ["Bash","Read","Write","Edit","Glob","Grep","WebFetch"] |
Upgrade Next.js
Upgrade the current project to the latest Next.js version following official migration guides.
Instructions
-
Detect current version: Read package.json to identify the current Next.js version and related dependencies (React, React DOM, etc.)
-
Fetch the latest upgrade guide: Use WebFetch to get the official upgrade documentation:
-
Determine upgrade path: Based on current version, identify which migration steps apply. For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15 → 16).
-
Run codemods first: Next.js provides codemods to automate breaking changes:
npx @next/codemod@latest <transform> <path>
Common transforms:
next-async-request-api - Updates async Request APIs (v15)
next-request-geo-ip - Migrates geo/ip properties (v15)
next-dynamic-access-named-export - Transforms dynamic imports (v15)
-
Update dependencies: Upgrade Next.js and peer dependencies using the repo's package manager (detect via lockfile: pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm):
pnpm add next@latest react@latest react-dom@latest
-
Review breaking changes: Check the upgrade guide for manual changes needed:
- API changes (e.g., async params in v15)
- Configuration changes in
next.config.js
- Deprecated features being removed
-
Update TypeScript types (if applicable):
pnpm add -D @types/react@latest @types/react-dom@latest
-
Test the upgrade:
- Run
pnpm build to check for build errors
- Run
pnpm dev and test key functionality