- name
- next-upgrade
- description
- Upgrade Next.js to the latest version following official migration guides and codemods
- argument-hint
- [target-version]
Upgrade Next.js
Upgrade the current project to the latest Next.js version following official migration guides.
Instructions
- Detect current version: Read
package.jsonto 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:
- Codemods: https://nextjs.org/docs/app/guides/upgrading/codemods - Version-specific guides (adjust version as needed): - https://nextjs.org/docs/app/guides/upgrading/version-16 - https://nextjs.org/docs/app/guides/upgrading/version-15 - https://nextjs.org/docs/app/guides/upgrading/version-14
- Determine upgrade path: Based on current version, identify which migration steps apply. For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15).
- 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 together:
npm install 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):
npm install @types/react@latest @types/react-dom@latest- Test the upgrade:
- Run npm run build to check for build errors - Run npm run dev and test key functionality