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

1. Detect current version: Read package.json to identify the current Next.js version and related dependencies (React, React DOM, etc.)

2. Fetch the latest upgrade guide: Use WebFetch to get the official upgrade documentation:

3. Codemods: https://nextjs.org/docs/app/building-your-application/upgrading/codemods

4. Version-specific guides (adjust version as needed):

   • https://nextjs.org/docs/app/building-your-application/upgrading/version-15
   • https://nextjs.org/docs/app/building-your-application/upgrading/version-14

5. Determine upgrade path: Based on current version, identify which migration steps apply. For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15).

6. Run codemods first: Next.js provides codemods to automate breaking changes:
   bash npx @next/codemod@latest <transform> <path>
   Common transforms:

7. next-async-request-api - Updates async Request APIs (v15)
8. next-request-geo-ip - Migrates geo/ip properties (v15)

9. next-dynamic-access-named-export - Transforms dynamic imports (v15)

10. Update dependencies: Upgrade Next.js and peer dependencies together:
    bash npm install next@latest react@latest react-dom@latest

11. Review breaking changes: Check the upgrade guide for manual changes needed:

12. API changes (e.g., async params in v15)
13. Configuration changes in next.config.js

14. Deprecated features being removed

15. Update TypeScript types (if applicable):
    bash npm install @types/react@latest @types/react-dom@latest

16. Test the upgrade:

17. Run npm run build to check for build errors
18. Run npm run dev and test key functionality