1---
2name: next-upgrade
3description: Upgrade Next.js to the latest version following official migration guides and codemods
4argument-hint: "[target-version]"
5---
6 
7# Upgrade Next.js
8 
9Upgrade the current project to the latest Next.js version following official migration guides.
10 
11## Instructions
12 
131. **Detect current version**: Read `package.json` to identify the current Next.js version and related dependencies (React, React DOM, etc.)
14 
152. **Fetch the latest upgrade guide**: Use WebFetch to get the official upgrade documentation:
16   - Codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
17   - Version-specific guides (adjust version as needed):
18     - https://nextjs.org/docs/app/guides/upgrading/version-16 
19     - https://nextjs.org/docs/app/guides/upgrading/version-15
20     - https://nextjs.org/docs/app/guides/upgrading/version-14
21 
223. **Determine upgrade path**: Based on current version, identify which migration steps apply. For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15).
23 
244. **Run codemods first**: Next.js provides codemods to automate breaking changes:
25   ```bash
26   npx @next/codemod@latest <transform> <path>
27   ```
28   Common transforms:
29   - `next-async-request-api` - Updates async Request APIs (v15)
30   - `next-request-geo-ip` - Migrates geo/ip properties (v15)
31   - `next-dynamic-access-named-export` - Transforms dynamic imports (v15)
32 
335. **Update dependencies**: Upgrade Next.js and peer dependencies together:
34   ```bash
35   npm install next@latest react@latest react-dom@latest
36   ```
37 
386. **Review breaking changes**: Check the upgrade guide for manual changes needed:
39   - API changes (e.g., async params in v15)
40   - Configuration changes in `next.config.js`
41   - Deprecated features being removed
42 
437. **Update TypeScript types** (if applicable):
44   ```bash
45   npm install @types/react@latest @types/react-dom@latest
46   ```
47 
488. **Test the upgrade**:
49   - Run `npm run build` to check for build errors
50   - Run `npm run dev` and test key functionality
51