/nextjs-upgrade

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 (HIGH)**

Workflow: Upgrade Next.js to New Major Version

1. Check current versions of `next`, `react`, `react-dom` in `package.json` 2. Plan incremental path (e.g., v13 -> v14 -> v15; never skip majors) 3. Run codemods: `npx @next/codemod@latest <transform> <path>` 4. Update dependencies: See [implementation examples](references/example.md) 5. Verify async APIs: ensure `cookies()`, `headers()`, `params` awaited (v15+) 6. Audit `fetch` caching: v15 defaults to `no-store`; add `force-cache` where needed 7. Run `next build` and fix hydration or Turbopack errors 8. 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.

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

• incremental
• one major