next-upgrade_skill

Overview

This skill automates and guides upgrading a Next.js project to the latest official release, following Next.js migration guides and recommended codemods. It detects the current Next.js and related dependency versions, constructs an incremental upgrade plan, and runs codemods and dependency updates while flagging manual breaking-change work. The goal is a safe, testable migration with clear next steps for any required manual fixes.

How this skill works

The skill reads package.json to determine current Next.js, React, and related versions and fetches the official upgrade and codemod documentation. It maps the project version to the appropriate stepwise upgrade path (minor or major jumps), recommends and executes codemods first, updates packages together, and lists manual changes that require human review. Finally, it directs the user to run build and dev commands to validate the upgrade.

When to use it

• You want to move a project to the latest Next.js version safely.
• A major Next.js release introduces breaking changes you must apply incrementally.
• You need to run official codemods before manual editing to reduce migration work.
• You want a reproducible upgrade plan that includes dependency and type updates.
• You need to validate the upgrade with build and runtime tests.

Best practices

• Detect current versions from package.json before any changes to determine an incremental path.
• Run official codemods first (npx @next/codemod@latest) to automate common breaking changes.
• Upgrade Next.js and its peer dependencies (React, React DOM) together to avoid mismatched APIs.
• Commit or create a branch before running codemods so changes are reviewable and revertible.
• Run npm run build and thorough runtime tests after updates to catch build-time and runtime regressions.

Example use cases

• Upgrade a v13 project to v16 by applying codemods for each major step and updating dependencies incrementally.
• Migrate async Request API usages using next-async-request-api codemod, then manually fix new async function signatures.
• Prepare a CI pipeline by adding build and test steps after upgrading to verify production readiness.
• Update TypeScript projects by installing latest @types/react and @types/react-dom after dependency upgrades.