Agent-Skills.md

Agent Skills: Next.js Upgrade Protocol

Next.js version migrations using official guides and codemods. Use when migrating a Next.js project to a new major version using codemods. (triggers: package.json, next upgrade, migration guide, codemod)

UncategorizedID: hoangnguyen0403/agent-skills-standard/nextjs-upgrade

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/nextjs/nextjs-upgrade

Skill Files

Browse the full folder contents for nextjs-upgrade.

Download Skill

Loading file tree…

skills/nextjs/nextjs-upgrade/SKILL.md

Skill Metadata

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. (triggers: package.json, 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 a 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
  5. Verify async APIs: ensure cookies(), headers(), params are 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 the 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 an incremental upgrade (v13 -> v14, then v14 -> v15). Follow the official Next.js Migration Guides.
  • Automated Codemods: Use npx @next/codemod@latest <transform> <path> to automate syntax migration.
  • Breaking Changes (v15): Respond to the next-async-request-api transform by ensuring params, searchParams, cookies(), and headers() are 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 a 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() is fatal.