home / skills / vercel-labs / next-skills / next-upgrade

next-upgrade skill

safe

This skill guides you upgrade Next.js to the latest version following official migration guides, codemods, and dependency updates.

npx playbooks add skill vercel-labs/next-skills --skill next-upgrade

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: next-upgrade
description: Upgrade Next.js to the latest version following official migration guides and codemods
argument-hint: "[target-version]"
---

# Upgrade Next.js

Upgrade the current project to the latest Next.js version following official migration guides.

## Instructions

1. **Detect current version**: Read `package.json` to identify the current Next.js version and related dependencies (React, React DOM, etc.)

2. **Fetch the latest upgrade guide**: Use WebFetch to get the official upgrade documentation:
   - Codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
   - Version-specific guides (adjust version as needed):
     - https://nextjs.org/docs/app/guides/upgrading/version-16 
     - https://nextjs.org/docs/app/guides/upgrading/version-15
     - https://nextjs.org/docs/app/guides/upgrading/version-14

3. **Determine upgrade path**: Based on current version, identify which migration steps apply. For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15).

4. **Run codemods first**: Next.js provides codemods to automate breaking changes:
   ```bash
   npx @next/codemod@latest <transform> <path>
   ```
   Common transforms:
   - `next-async-request-api` - Updates async Request APIs (v15)
   - `next-request-geo-ip` - Migrates geo/ip properties (v15)
   - `next-dynamic-access-named-export` - Transforms dynamic imports (v15)

5. **Update dependencies**: Upgrade Next.js and peer dependencies together:
   ```bash
   npm install next@latest react@latest react-dom@latest
   ```

6. **Review breaking changes**: Check the upgrade guide for manual changes needed:
   - API changes (e.g., async params in v15)
   - Configuration changes in `next.config.js`
   - Deprecated features being removed

7. **Update TypeScript types** (if applicable):
   ```bash
   npm install @types/react@latest @types/react-dom@latest
   ```

8. **Test the upgrade**:
   - Run `npm run build` to check for build errors
   - Run `npm run dev` and test key functionality

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.

FAQ

Do I have to upgrade major versions one at a time?

Yes. For major breaking changes, upgrade incrementally (for example 13→14→15) and run codemods at each step to reduce manual fixes.

Will codemods handle everything automatically?

Codemods automate many repetitive changes but not all. Expect to review manual breaking changes, configuration updates, and runtime behavior after running codemods.