Loaded automatically when its description matches the active task. Read only the section you need, then follow the link to the relevant reference file.
Use this skill when
Building Next.js App Router apps with Server Components, Server Actions, route handlers
shadcn/ui setup without App Router context → shadcn
Remix, SvelteKit, Nuxt, Astro → their dedicated skills
Tailwind config / design tokens → tailwind
Client-only TanStack Query SPA → tanstack-query
Purpose
Next.js 16 is the dominant React meta-framework. App Router is the only first-class architecture since 15. Version 16 completes the transition: async Dynamic APIs (params, searchParams, cookies, headers are Promises), 'use cache' replaces the old fetch cache API, Turbopack is the default bundler, PPR stabilizes.
This skill covers file conventions, data fetching with the cache directive, rendering modes, Server Actions, middleware, error boundaries, and 15→16 migration. Hands off to react for component internals, vercel for deploy, shadcn/tailwind for design.
Capabilities
Each line below points to the canonical reference. The reference owns code, edge cases, and gotchas — do not duplicate them here.
Troubleshooting — 'use cache' not invalidating, Server Action 413, middleware doesn't run, hydration mismatch, PPR debugging. → references/troubleshooting.md
Wrong vs right — sync vs async cookies(), cache: 'no-store' vs dynamic = 'force-dynamic', raw fetch POST vs Server Action validation. → references/wrong-vs-right.md
Behavioral Traits
Starts every component as Server Component; adds 'use client' only for hooks/events
Awaits params, searchParams, cookies(), headers() — never sync access
Uses 'use cache' + cacheTag/cacheLife instead of fetch cache options or unstable_cache
Scopes <Suspense> at the smallest meaningful unit — never wraps the whole page
Pairs Server Actions with useActionState + Zod — no raw fetch POST from Client Components
Names the middleware file proxy.ts in Next 16
Uses generateMetadata (async) for dynamic; export const metadata for static — never both in the same file
Calls revalidateTag from Server Actions or route handlers, not Client Components
Places 'use cache' functions in dedicated lib/ or data/ files
Always sets alt on next/image; provides width+height or fill+sizes
Important Constraints
NEVER access params.id synchronously — params is a Promise; await first
NEVER call cookies() / headers() synchronously — both Promises in Next 16
NEVER import a Server Component inside a Client Component — breaks RSC boundary
NEVER mix 'use server' and non-action exports in the same file — colocate in actions.ts
NEVER substitute revalidatePath for revalidateTag when a tag exists — tag-based is precise
NEVER pass secrets to Client Components via props from Server Components
NEVER ship proxy.ts without matcher — middleware then runs on every request including static assets
ALWAYS handle isPending in useActionState — disable submit to prevent duplicate submissions
ALWAYS use notFound() / forbidden() / unauthorized() from next/navigation — they throw correctly
ALWAYS type generateMetadata as Promise<Metadata>
Related Skills
✓ marks active skills; unmarked are cascade markers (generate via skill-evaluation on first real touch).
Language & React layer
✓ typescript — TS 5.9
✓ react — React 19 component patterns
Styling
✓ tailwind — Tailwind CSS 4
✓ shadcn — shadcn/ui
Data fetching / forms
✓ tanstack-query — Client-side cache for CSR islands
✓ react-hook-form — When useActionState is insufficient
✓ zod — Schema validation in Server Actions and route handlers
