| name | nextjs-upgrade |
| description | Next.js version migrations using official guides and codemods. Use when migrating a Next.js project to a new major version using codemods. |
| metadata | {"triggers":{"files":["package.json"],"keywords":["next upgrade","migration guide","codemod"]}} |
Next.js Upgrade Protocol
Automated and manual migration steps for Next.js version upgrades (e.g., v14 to v15).
Priority: P1 (OPERATIONAL)
Workflow: Upgrade Next.js to New Major Version
- Check current versions of
next, react, react-dom in package.json
- Plan incremental path (e.g., v13 -> v14 -> v15; never skip majors)
- Run codemods:
npx @next/codemod@latest <transform> <path>
- Update dependencies:
See implementation examples
- Verify async APIs: ensure
cookies(), headers(), params awaited (v15+)
- Audit
fetch caching: v15 defaults to no-store; add force-cache where needed
- Run
next build and fix hydration or Turbopack errors
- Report codemod failures or manual fixes to team
Implementation Guidelines
- Upgrade Detection: Always check
package.json for versions of next, react, and react-dom.
- Planning: For major version jumps (v13 to v15), perform incremental upgrade (v13 -> v14, then v14 -> v15). Follow official Next.js Migration Guides.
- Automated Codemods: Use
npx @next/codemod@latest <transform> <path> to automate syntax migration.
- Breaking Changes (v15): Respond to
next-async-request-api transform by ensuring params, searchParams, cookies(), and headers() awaited.
- React Parity: Upgrade
react and react-dom to match Next.js peer dependencies (e.g., React 19 for Next.js 15).
- Validation: Run
next dev and next build after each incremental step. Check console errors for hydration warnings.
Anti-Patterns
- No major version skipping: Upgrade one major version at time (13 -> 14, then 14 -> 15).
- No manual breaking-change fixes: Always run
npx @next/codemod@latest transforms first.
- No assumed caching behavior post-upgrade: v15 defaults to
no-store; audit all fetch calls.
- No async page functions in Pages Router:
export default async function Page() fatal.
