Next Upgrade
Upgrade an existing Next.js app to a target major version using official docs, codemods, and coordinated React peer dependency bumps.
Overview
next-upgrade is an agent skill for the Build phase that upgrades a Next.js project using official migration guides, codemods, and synchronized dependency updates.
Install
npx skills add https://github.com/vercel/nextjs-skills --skill next-upgradeWhat is this skill?
- Reads package.json to detect current Next.js, React, and related dependency versions
- Fetches official Next.js upgrading guides and codemod documentation via WebFetch
- Plans incremental major-version paths (e.g. 13 → 14 → 15) instead of risky single jumps
- Runs @next/codemod transforms such as next-async-request-api and next-dynamic-access-named-export
- Bumps next@latest together with peer dependencies after codemods complete
- Documents incremental major-version upgrade paths (e.g. 13 → 14 → 15)
- Lists multiple named @next/codemod transforms for v15-class breaking changes
Adoption & trust: 1 installs on skills.sh; 919 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You are several Next.js majors behind and fear silent breaking changes if you only run npm install next@latest.
Who is it for?
Solo builders maintaining a Next.js App Router or Pages app who want agent-driven steps that mirror nextjs.org upgrading docs.
Skip if: Greenfield scaffolds with no existing Next app, or teams that forbid shell/npm and codemod execution in the agent environment.
When should I use this skill?
Upgrade Next.js to the latest version following official migration guides and codemods; optional argument-hint target-version.
What do I get? / Deliverables
You get a version-aware upgrade path, codemods applied in order, and dependencies bumped to match the target Next.js release.
- Updated package.json dependency versions for Next and peers
- Codemod-applied source tree aligned with target Next release
Recommended Skills
Journey fit
Framework upgrades happen while you are actively building or extending the product, before you ship breaking routing or async API changes. Next.js is the primary App Router / React UI stack; this skill targets package.json, codemods, and app-level breaking changes—not generic backend-only services.
How it compares
Use instead of asking the model to freestyle a Next upgrade from memory without fetching current codemod names.
Common Questions / FAQ
Who is next-upgrade for?
Indie and solo developers who ship Next.js products and need a structured upgrade when React or Next releases move async APIs, routing, or bundling behavior.
When should I use next-upgrade?
During Build when you are about to bump Next for a feature branch, before Ship when you need parity with Vercel defaults, or during Operate iterate when security patches require a framework lift.
Is next-upgrade safe to install?
It instructs the agent to run codemods and package installs on your repo; review the Security Audits panel on this page and dry-run on a git branch before merging.
SKILL.md
READMESKILL.md - Next Upgrade
# 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