nextjs-upgrade
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)
Best use case
nextjs-upgrade is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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)
Teams using nextjs-upgrade should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/nextjs-upgrade/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How nextjs-upgrade Compares
| Feature / Agent | nextjs-upgrade | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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)
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Next.js Upgrade Protocol
Automated and manual migration steps for Next.js version upgrades (e.g., v14 → v15).
## **Priority: P1 (OPERATIONAL)**
## 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.
- **Reporting**: Report all **codemod failures** or manual fixes needed to the team.
## **3. Dependency Update**
Upgrade Next.js and peer dependencies in sync:
```bash
# Using npm
npm install next@latest react@latest react-dom@latest
# Update Types
npm install --save-dev @types/react@latest @types/react-dom@latest
```
## **4. Manual Verification Rules**
1. **Async Context**: Verify all uses of `cookies()`, `headers()`, and route `params` are now awaited.
2. **Metadata**: Ensure `generateMetadata` types match the new async `params` signature.
3. **Caching**: In v15+, `fetch` defaults to `{ cache: 'no-store' }`. If you need the old behavior, explicitly set `{ cache: 'force-cache' }`.
## **5. Testing Build**
- Run `npm run build` immediately after codemods and package updates.
- Check for "Hydration failed" or "Turbopack" compatibility errors if using `--turbo`.
## 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.Related Skills
exa-upgrade-migration
Upgrade exa-js SDK versions and handle breaking changes safely. Use when upgrading the Exa SDK, detecting deprecations, or migrating between exa-js versions. Trigger with phrases like "upgrade exa", "exa update", "exa breaking changes", "update exa-js", "exa new version".
evernote-upgrade-migration
Upgrade Evernote SDK versions and migrate between API versions. Use when upgrading SDK, handling breaking changes, or migrating to newer API patterns. Trigger with phrases like "upgrade evernote sdk", "evernote migration", "update evernote", "evernote breaking changes".
elevenlabs-upgrade-migration
Upgrade ElevenLabs SDK versions and migrate between API model generations. Use when upgrading the elevenlabs-js or elevenlabs Python SDK, migrating from v1 to v2 models, or handling deprecations. Trigger: "upgrade elevenlabs", "elevenlabs migration", "elevenlabs breaking changes", "update elevenlabs SDK", "migrate elevenlabs model", "eleven_v3 migration".
documenso-upgrade-migration
Manage Documenso API version upgrades and SDK migrations. Use when upgrading from v1 to v2 API, updating SDK versions, or migrating between Documenso versions. Trigger with phrases like "documenso upgrade", "documenso v2 migration", "update documenso SDK", "documenso API version".
deepgram-upgrade-migration
Plan and execute Deepgram SDK upgrades and model migrations. Use when upgrading SDK versions (v3->v4->v5), migrating models (Nova-2 to Nova-3), or planning API version transitions. Trigger: "upgrade deepgram", "deepgram migration", "update deepgram SDK", "deepgram version upgrade", "nova-3 migration".
databricks-upgrade-migration
Upgrade Databricks runtime versions and migrate between features. Use when upgrading DBR versions, migrating to Unity Catalog, or updating deprecated APIs and features. Trigger with phrases like "databricks upgrade", "DBR upgrade", "databricks migration", "unity catalog migration", "hive to unity".
customerio-upgrade-migration
Plan and execute Customer.io SDK upgrades and migrations. Use when upgrading customerio-node versions, migrating from legacy APIs, or updating to new SDK patterns. Trigger: "upgrade customer.io", "customer.io migration", "update customer.io sdk", "customer.io breaking changes".
cursor-upgrade-migration
Upgrade Cursor versions, migrate from VS Code, and transfer settings between machines. Triggers on "upgrade cursor", "update cursor", "cursor migration", "cursor new version", "vs code to cursor", "cursor changelog".
coreweave-upgrade-migration
Upgrade CoreWeave deployments and migrate between GPU types. Use when migrating from A100 to H100, upgrading CUDA versions, or updating inference server versions. Trigger with phrases like "upgrade coreweave", "coreweave gpu migration", "coreweave cuda upgrade", "migrate coreweave".
cohere-upgrade-migration
Migrate from Cohere API v1 to v2 and upgrade SDK versions. Use when upgrading cohere-ai SDK, migrating from CohereClient to CohereClientV2, or handling breaking changes between API versions. Trigger with phrases like "upgrade cohere", "cohere migration", "cohere v1 to v2", "update cohere SDK", "cohere breaking changes".
coderabbit-upgrade-migration
Update CodeRabbit configuration for new features, migrate between plans, and adopt new capabilities. Use when CodeRabbit releases new features, upgrading from Free to Pro plan, or updating .coderabbit.yaml schema for new options. Trigger with phrases like "upgrade coderabbit", "coderabbit new features", "update coderabbit config", "coderabbit plan upgrade", "coderabbit changelog".
clickup-upgrade-migration
Migrate between ClickUp API versions (v2 to v3) and handle breaking changes. Use when upgrading API versions, adapting to endpoint changes, or migrating between ClickUp plan tiers. Trigger: "upgrade clickup API", "clickup v2 to v3", "clickup breaking changes", "clickup API migration", "clickup deprecation".