Agent-skills-standard 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)

install

source · Clone the upstream repo

git clone https://github.com/HoangNguyen0403/agent-skills-standard

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/HoangNguyen0403/agent-skills-standard "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/nextjs/nextjs-upgrade" ~/.claude/skills/hoangnguyen0403-agent-skills-standard-nextjs-upgrade && rm -rf "$T"

manifest: skills/nextjs/nextjs-upgrade/SKILL.md

source content

Next.js Upgrade Protocol

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

Priority: P1 (OPERATIONAL)

Workflow: Upgrade Next.js to New Major Version

Check current versions of
```
next
```
,
```
react
```
,
```
react-dom
```
in
```
package.json
```
Plan incremental path (e.g., v13 -> v14 -> v15; never skip majors)

Run codemods:

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

Update dependencies: See implementation examples
Verify async APIs: ensure
```
cookies()
```
,
```
headers()
```
,
```
params
```
awaited (v15+)
Audit
```
fetch
```
caching: v15 defaults to
```
no-store
```
; add
```
force-cache
```
where needed
Run
```
next build
```
and fix hydration or Turbopack errors
Report codemod failures or manual fixes to team

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 incremental upgrade (v13 -> v14, then v14 -> v15). Follow official Next.js Migration Guides.
Automated Codemods: Use
```
npx @next/codemod@latest <transform> <path>
```
to automate syntax migration.
Breaking Changes (v15): Respond to
```
next-async-request-api
```
transform by ensuring
```
params
```
,
```
searchParams
```
,
```
cookies()
```
, and
```
headers()
```
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.

Anti-Patterns

No major version skipping: Upgrade one major version at 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()
```
fatal.