next-upgrade

Overview of next-upgrade skill

What next-upgrade does

The next-upgrade skill helps an agent upgrade a real Next.js project to a newer major version using the official migration guides and codemods, instead of guessing from memory. Its job is practical: detect the current next version in your app, map the safest upgrade path, apply the right codemods first, then update dependencies and review breaking changes that still need manual edits.

Who should use this next-upgrade skill

This skill is best for developers maintaining an existing Next.js codebase who want an AI assistant to plan or execute an upgrade with less drift from official guidance. It is especially useful when:

• your project is more than one major version behind
• you want a repo-aware upgrade plan, not a generic checklist
• you need help identifying version-specific codemods and dependency alignment
• you want support inside a Code Editing workflow, not just a browser summary

Real job-to-be-done

Most users do not need “information about Next.js upgrades.” They need to get from a currently working app to a newer Next.js version without breaking routing, React compatibility, build output, or runtime APIs. The next-upgrade skill is aimed at that decision and execution path.

What makes next-upgrade different from a normal prompt

A plain prompt may suggest broad upgrade advice. next-upgrade is narrower and more useful because it is structured around:

• reading your package.json first
• checking official Next.js upgrade guides for the target version
• handling major-version jumps incrementally
• prioritizing official codemods before hand edits
• pairing next, react, and react-dom upgrades correctly

What it does not do for you

The skill does not eliminate the need for validation. It can guide code changes and dependency updates, but you still need to run your app, tests, linting, and build checks. It is also not a substitute for framework-specific knowledge in heavily customized setups such as monorepos, unusual bundler integrations, or deeply patched server/runtime behavior.

How to Use next-upgrade skill

Install context for next-upgrade

Install the skill into your AI coding environment so it can be invoked while working inside the repository you want to upgrade. A common install pattern is:

npx skills add https://github.com/vercel-labs/next-skills --skill next-upgrade

If your environment already exposes GitHub skills from vercel-labs/next-skills, you may only need to call next-upgrade directly.

How to invoke next-upgrade in practice

The repository indicates an argument hint of [target-version], so the cleanest usage is to provide the desired version explicitly, for example:

• Use next-upgrade for Next.js 16
• Run next-upgrade targeting v15
• Apply the next-upgrade skill to move this app from 13 to 15 incrementally

If you do not know the target yet, ask for a plan first:

• Use next-upgrade to inspect this repo and recommend the safest target version

What input the skill needs

next-upgrade works best when the agent can inspect:

• package.json
• lockfile such as package-lock.json, pnpm-lock.yaml, or yarn.lock
• workspace config if the app is in a monorepo
• the app directory structure, especially whether you use app/ or pages/
• CI or build commands used to verify the upgrade

Minimum useful input:

• current Next.js version
• package manager
• desired target version
• whether you want planning only or actual code edits

Turn a rough goal into a strong next-upgrade prompt

Weak prompt:

• Upgrade my app

Better prompt:

• Use next-upgrade to inspect package.json, determine the current Next.js version, upgrade this project to Next.js 15 using official migration guides, run the relevant @next/codemod transforms first, then update next/react/react-dom together and summarize any manual follow-up changes.

Best prompt when your repo is non-trivial:

• Use next-upgrade for Code Editing on this monorepo app in apps/web. Read apps/web/package.json, identify the current next/react versions, plan the required incremental major upgrades to reach Next.js 16, apply official codemods where relevant, update dependencies with pnpm-compatible commands, and leave a checklist of manual verification steps for build, routing, and runtime APIs.

That extra specificity improves output because the skill itself is concise; your prompt supplies repo boundaries, package manager, and execution scope.

Recommended workflow before making edits

A reliable next-upgrade usage flow is:

1. inspect package.json and current dependency versions
2. choose the target version
3. fetch the official Next.js upgrade guide for each major step involved
4. run codemods before manual cleanup
5. update next, react, and react-dom
6. run lint, typecheck, tests, and production build
7. fix remaining breaking changes surfaced by the guide or runtime errors

If you are several versions behind, do not jump blindly. Ask the agent to handle 13 -> 14 -> 15 -> 16 as separate upgrade steps.

Repository file to read first

Start with skills/next-upgrade/SKILL.md in the upstream repository:

• https://github.com/vercel-labs/next-skills/tree/main/skills/next-upgrade

It is a short skill, so there are not many supporting files to inspect. The main value is the workflow encoded in SKILL.md: detect version, fetch official docs, upgrade incrementally, run codemods first, then update dependencies.

Official documentation this skill depends on

The skill explicitly points to official Next.js upgrade resources, including:

• codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
• version guides such as:
  • 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

This matters for adoption: next-upgrade is only as good as the agent’s willingness to fetch and follow those guides, rather than relying on stale framework knowledge.

Codemods come first, not last

One of the strongest parts of the next-upgrade guide is sequencing. It tells the agent to run official codemods early:
npx @next/codemod@latest <transform> <path>

Examples surfaced by the skill include:

• next-async-request-api
• next-request-geo-ip
• next-dynamic-access-named-export

That ordering is important because codemods often handle repetitive breaking changes faster and more safely than hand-editing after dependency bumps.

Dependency updates to ask for explicitly

When using next-upgrade, ask the agent to upgrade peer dependencies together. The skill specifically centers this pattern:
npm install next@latest react@latest react-dom@latest

Even if you use pnpm or yarn, the point stands: treat next, react, and react-dom as a coordinated set unless the official guide says otherwise.

next-upgrade for Code Editing

For Code Editing, next-upgrade is most useful when you let the agent both inspect and modify files, not just produce a plan. Good tasks include:

• updating dependency ranges in package.json
• applying codemod commands
• changing APIs affected by breaking changes
• leaving inline comments or a migration summary for manual review

It is less useful if your environment cannot access the repository files or external docs, because the skill’s advantage comes from repo inspection plus official guide retrieval.

Practical constraints and tradeoffs

Use next-upgrade when you want a disciplined path, but expect some limits:

• it does not encode every version nuance locally; it expects live guide lookup
• it is strongest on standard Next.js apps, not highly customized infra
• it does not provide built-in project-specific test automation
• it may need extra prompting for monorepos, subapps, or non-root package files

In short, the skill reduces guesswork, but your prompt still has to define scope clearly.

next-upgrade skill FAQ

Is next-upgrade better than a generic upgrade prompt?

Usually yes, if you want a repeatable upgrade process. A generic prompt may produce plausible but outdated advice. next-upgrade is anchored to official migration guides, codemods, and version detection from your project files.

Is the next-upgrade skill beginner-friendly?

Yes, with one caveat: beginners should use it in planning mode first. Ask for:

• current version detection
• target recommendation
• codemods to run
• likely manual changes
• verification checklist

That makes the output easier to review before allowing edits.

Do I need to know the target version first?

No. You can ask next-upgrade to inspect the repo and recommend the safest target. But if you already know you need a specific version for platform or dependency reasons, giving the target up front produces a cleaner plan.

When should I not use next-upgrade?

Skip next-upgrade if:

• you are creating a new app rather than upgrading one
• your issue is unrelated to a version migration
• your stack depends on custom internals not covered by official docs
• you only need a one-line command and already know the exact version path

Can next-upgrade handle multi-version jumps?

Yes, but it should do so incrementally. The skill explicitly favors stepwise major upgrades rather than a single blind leap. If your app is far behind, ask for a staged plan and checkpoints after each major version.

Does it work only for app router projects?

No, but the official guides it fetches may emphasize newer Next.js patterns. If your codebase still uses older conventions, ask the agent to identify which parts of the guide apply and which do not before making edits.

How to Improve next-upgrade skill

Give next-upgrade clearer repo boundaries

The fastest way to improve results is to tell the agent exactly where the Next.js app lives. In a monorepo, specify:

• app path like apps/web
• package manager
• workspace tool
• whether edits should stay inside that app only

Without that, the skill may inspect the wrong package.json or propose commands at the wrong level.

Ask for a two-phase output

A strong pattern is:

1. plan only
2. execute edits

Example:

• Use next-upgrade to first produce an upgrade plan with required codemods and risks. After I approve it, apply the changes.

This reduces accidental broad edits and makes the skill more trustworthy on production codebases.

Provide stronger verification criteria

Do not just ask for “upgrade successfully.” Ask the agent to verify with concrete commands such as:

• install
• lint
• typecheck
• unit tests
• production build

This improves next-upgrade usage because the agent can optimize for a passing repo, not just updated dependency lines.

Name the failure modes you care about

If your priority is avoiding specific regressions, say so. For example:

• Prioritize route behavior and middleware compatibility
• Watch for request API changes introduced in newer Next.js versions
• Do not migrate unrelated code while applying next-upgrade

These constraints shape better edits than a broad “make it work” request.

Ask for codemod selection rationale

A useful improvement prompt is:

• List which @next/codemod transforms apply to this repo and why before running them

This helps you review whether the agent is matching transforms to actual code patterns instead of running codemods indiscriminately.

Common failure modes with next-upgrade

Typical weak-result patterns include:

• upgrading dependencies without checking the current version first
• skipping intermediate major versions
• hand-editing before reviewing codemods
• ignoring react and react-dom alignment
• assuming the root package.json is the app package in a monorepo

If you see these, stop and ask for a version-by-version plan.

How to iterate after the first output

After the first pass, ask for a tighter second pass focused on what failed:

• Re-run next-upgrade analysis based on these build errors
• Compare the remaining errors against the official v15 guide
• Propose the smallest manual edits still needed after codemods

This is better than restarting from scratch because the skill is designed around migration steps, not one-shot perfection.

Best prompt pattern for higher-quality next-upgrade results

A compact high-signal template:

Use next-upgrade on <path>. Detect the current Next.js version from package.json, determine the correct incremental upgrade path to <target-version>, fetch the official migration guides for each step, identify and run the applicable @next/codemod transforms first, then update next/react/react-dom together. After edits, summarize breaking changes addressed, remaining manual follow-ups, and the exact verification commands I should run.

That prompt gives the next-upgrade skill enough structure to produce output that is materially better than a generic Code Editing request.