home / skills / hoangnguyen0403 / agent-skills-standard / upgrade

upgrade skill

safe

This skill streamlines Next.js upgrades by guiding incremental migrations, codemod execution, and verification to ensure smooth v14+ transitions.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill upgrade

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

Files (1)

SKILL.md

1.8 KB

---
name: next-upgrade
description: Next.js version migrations using official guides and codemods.
metadata:
  labels: [nextjs, upgrade, migration, codemods]
  triggers:
    files: ['package.json']
    keywords: [next upgrade, migration guide, codemod]
---

# Next.js Upgrade Protocol

Automated and manual migration steps for Next.js version upgrades (e.g., v14 → v15).

## **Priority: P1 (OPERATIONAL)**

## **1. Detection & Planning**

- Check `package.json` for current `next`, `react`, and `react-dom` versions.
- **Incremental Upgrades**: Jumps across multiple major versions (e.g., 13 → 15) MUST be done incrementally (13 → 14 then 14 → 15).

## **2. Automated Codemods**

Run Next.js codemods to handle breaking syntax changes:

```bash
npx @next/codemod@latest <transform> <path>
```

**Common Transforms (v15):**

- `next-async-request-api`: Transforms `params`, `searchParams`, `cookies()`, and `headers()` into awaited Promises.
- `next-request-geo-ip`: Migrates legacy geo/ip properties.
- `next-dynamic-access-named-export`: Fixes dynamic import syntax.

## **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`.

Overview

This skill automates and guides Next.js version migrations using official codemods and practical manual checks. It focuses on safe, incremental upgrades and synchronizing peer dependencies to avoid runtime and build failures. The goal is a predictable upgrade path with clear verification steps and minimal developer friction.

How this skill works

It inspects package.json for Next.js, React, and react-dom versions and recommends incremental major-version steps. It runs Next.js codemods to apply common breaking changes, updates peer dependencies, and provides a compact checklist for manual verification. Finally, it enforces immediate build and test runs to surface compatibility issues like hydration or Turbopack errors.

When to use it

Upgrading Next.js across a single major version (e.g., 14 → 15).
Performing multi-major jumps (e.g., 13 → 15) where incremental migration is required.
After pull requests that change server/client APIs like cookies(), headers(), or params.
Before changing build tooling or enabling Turbopack in CI.
When aligning project React and types packages with a Next.js major upgrade.

Best practices

Always perform upgrades incrementally across major versions to limit breaking changes per step.
Run official @next/codemod transforms before changing source manually to automate common migrations.
Update next, react, react-dom and dev types in a single commit to keep runtime and types in sync.
Immediately run npm run build and full tests after codemods and dependency updates to catch errors early.
Verify all formerly synchronous APIs (cookies(), headers(), params) are awaited and adjust generateMetadata types to match async signatures.

Example use cases

Migrate a Next.js 14 app to 15: run codemods, update dependencies, verify async API usage, and build.
Bring project types in sync: install latest @types/react and @types/react-dom after Next.js bump to eliminate type regressions.
Fix runtime fetch behavior after upgrade by auditing fetch cache defaults and setting { cache: 'force-cache' } where persistent caching is required.
Troubleshoot a CI build that failed post-upgrade by checking for hydratation errors and Turbopack compatibility flags.

FAQ

Do I need to run every codemod listed?

Run only the transforms relevant to your codebase. Start with transforms for async request APIs, geo/ip properties, and dynamic import fixes, then iterate based on build errors.

Can I skip updating @types packages?

No. Keep @types/react and @types/react-dom aligned with React to avoid type mismatches that can block builds or cause incorrect fixes.