nextjs
Version-aware Next.js rules. Use for ANY work in a project that depends on `next` — routes, pages, layouts, Server Components, Server Actions, data fetching, caching, middleware/proxy, next.config, ne
SKILL.md.claude/skills/nextjs/SKILL.md
GitHubNext.js (version-aware)
Never write Next.js code from memory of "the latest" version. APIs differ across majors (sync vs async params, caching defaults, middleware vs proxy). Code must match the version this project actually runs.
1. Resolve the version (once per session)
- If session context contains
[arsenal] stack:withnext@<version>, use it. - Otherwise resolve it from the package that owns the file being edited (monorepo: nearest
package.jsonabove that file), in this order:node_modules/next/package.json→"version"— installed, authoritative.- Lockfile entry (
package-lock.json,pnpm-lock.yaml,yarn.lock,bun.lock). dependencies.nextrange inpackage.json— use its lowest satisfying major and state that the version is unverified.
- Router:
app/orsrc/app/→ App Router;pages/orsrc/pages/→ Pages Router; both → follow the router of the file being edited.
2. Load exactly one reference
| Installed major | Read |
|---|---|
| 14 | references/v14.md |
| 15 | references/v15.md |
| 16 | references/v16.md |
No matching reference (≤ 13 or ≥ 17): do NOT extrapolate from the nearest file. Read the official upgrade guide for that major (https://nextjs.org/docs/app/guides/upgrading/version-<major>, index at https://nextjs.org/docs/llms.txt) and the project's existing code, and say the rules came from docs, not a curated reference.
For an API introduced in a later minor than the reference covers, confirm it exists in the installed type definitions (node_modules/next/*.d.ts) before using it.
3. Rules for every version
- Existing project conventions (router,
src/layout, data-fetching style, TS/JS) beat generic best practice. - In
app/, components are Server Components by default. Add'use client'only where state, effects, browser APIs, or event handlers are needed — as deep in the tree as possible, never on a layout by reflex. - Never import server-only code (DB clients, secrets,
next/headers) into a'use client'module. OnlyNEXT_PUBLIC_*env vars reach the browser. - Treat every Server Action as a public HTTP endpoint: validate input and check authorization inside the action.
- Do not upgrade
next/reactor run codemods unless the task asks for it. - Verify with the project's own scripts: type check first; run
next buildwhen routing, config, caching, or the server/client boundary changed — it catches errors the type check misses.