nextjs

• SKILL.mdcore · 3,218 bytes

# Next.js

House conventions for Next.js App Router (14+). Apply them to code you are writing or changing — don't migrate untouched routes unless asked.

## Conventions

- **App Router only.** Never add to `pages/`. If a project still has one, new work goes in `app/` and the two coexist until someone schedules the migration.
- **Server Components by default.** `'use client'` marks a leaf that needs interactivity, not a page. Everything above that marker ships to the browser too, so the boundary belongs as deep in the tree as it will go.
- **Verify caching behaviour against the installed version — it changed.** Through Next 14, `fetch` was cached by default and you opted out; from Next 15, `fetch`, Route Handlers, and client navigation are uncached by default and you opt in. Assuming the wrong default gives you either stale pages or an origin taking every request. Check `package.json`, then set the intent explicitly (`cache`, `next.revalidate`, or route segment config) rather than relying on whatever the default happens to be.
- **`params` and `searchParams` are Promises from Next 15 on** — `const { slug } = await params`. Code written against 14 destructures them synchronously and breaks on upgrade, so check the installed major before copying either form.
- **A `layout.tsx` auth check is not a security boundary.** Layouts don't re-render on every navigation between their child routes, so the check can be skipped on client-side transitions. Enforce access in middleware and again where the data is read; the layout check is UX, not enforcement.
- **Tag what you fetch, revalidate by tag.** `next: { tags: ['user'] }` plus `revalidateTag('user')` after a mutation invalidates exactly the affected data. Time-based revalidation is a guess about staleness; tags are a fact about it.
- **Server Actions are public endpoints.** They are reachable by anyone who can find the action ID, so every one re-checks auth and re-validates its input server-side. The form it was rendered behind proves nothing about the caller.
- **Fetch in the component that renders the data.** React dedupes identical requests within a render pass, so prop-drilling data down to avoid a "duplicate" fetch buys nothing and couples the tree.