NextJS

Setup

All persistent data for this skill lives in ~/Clawic/data/nextjs/. On first use, read setup.md for project integration.

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/nextjs/config.yaml.

Preference areas to record as the user reveals them:

• conventions — component/file naming, folder organization, barrel-file usage
• stack — TypeScript, ORM (Prisma/Drizzle), auth library, state management
• proactivity — how eagerly to flag caching/boundary/performance issues vs only on request
• safety posture — how proactively to surface auth hardening (data-access layer, CVE-2025-29927) vs only when asked

When To Use

• Building or debugging a Next.js App Router application — routing, rendering, data, deploy
• Boundary errors: "useState only works in Client Components", hydration mismatch, "functions cannot be passed to Client Components"
• Cache surprises: stale pages, data not updating, ISR behaving "randomly"
• Wiring auth: sessions, protected routes, role checks
• Shipping: Vercel, Docker, standalone server, static export
• Not for plain React questions (see react skill) or Pages Router deep-dives — App Router is assumed throughout

Architecture

~/Clawic/data/nextjs/
├── memory.md          # Project conventions, patterns
└── projects/          # Per-project learnings

See memory-template.md for the file formats. If you have data at an old location (~/nextjs/ or ~/clawic/nextjs/), move it to ~/Clawic/data/nextjs/.

Quick Reference

Core Rules

1. Server by Default, Client at the Leaves

'use client' marks a boundary, not one component: everything imported below it ships to the browser. Put interactivity in leaf components; a 'use client' layout de-RSCs its whole subtree.

2. Parallel Fetches or You Pay the Sum

Sequential awaits cost sum(t1..tn); Promise.all costs max(). Three 300ms fetches: 900ms sequential, 300ms parallel. Chain awaits only when one call genuinely needs the other's result.

3. One Dynamic Read Poisons the Whole Route

cookies(), headers(), or an uncached fetch anywhere in the tree — layouts included — forces the entire route to render per-request. Read them in the leaf that needs them, behind ``.

4. Dev Lies About Caching

next dev renders everything dynamically. Verify cache behavior only with next build && next start; debug headers and build-output symbols are in caching.md.

5. Middleware Redirects, the Data Layer Enforces

Middleware does optimistic cookie checks for UX; every Server Action, route handler, and query re-verifies the session. CVE-2025-29927 let a spoofed request header skip middleware entirely — patched versions and the data-access-layer pattern in auth.md.

6. Server Actions Are Public Endpoints

Anyone can POST to an action with its id; a hidden button protects nothing. First lines of every action: session check, then input validation.

7. Write, Revalidate, Then Redirect

Every mutating action ends with revalidatePath/revalidateTag, or the UI keeps serving stale cache. redirect() throws — call it after the try/catch, never inside one.

8. NEXT_PUBLIC_ Is Baked at Build Time

Inlined into the bundle during next build; changing it at runtime does nothing. Unprefixed vars stay server-only — and any differing public var means one Docker image per environment (deployment.md).

9. Suspense Converts Blocking Into Streaming

TTFB = the slowest await chain outside any Suspense boundary. Wrap each independent slow fetch in its own `` so the shell paints immediately.

Server vs Client

Decision: Start Server. Add 'use client' only for: useState, useEffect, event handlers, browser APIs.

The boundary is a serialization boundary. Props crossing server→client must serialize: plain objects, arrays, Date, Map, Set — yes; functions and class instances — no (exceptions: Server Actions passed as props, and Promises, which the client unwraps with use()). A Server Component can't be imported into a Client Component — pass it as children.

Version Gates

• next >=13.4 — App Router stable; everything here assumes it
• next 14 — fetch cached by default (the version where the default flips)
• next >=15 — fetch and GET route handlers uncached by default; params/searchParams are Promises, await them; React 19 (useActionState)
• next >=16 — Turbopack is the default bundler; synchronous params access removed; middleware.ts renamed proxy.ts (old name deprecated)

Traps

Where Experts Disagree

Related Skills

More Clawic skills, get them at https://clawic.com/skills/nextjs (install if the user confirms):

• react — React fundamentals and patterns
• typescript — Type safety for better DX
• prisma — Database ORM for Next.js apps
• tailwindcss — Styling with utility classes
• nodejs — Server runtime knowledge

Feedback

• If useful, star it: https://clawic.com/skills/nextjs
• Latest version: https://clawic.com/skills/nextjs

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/nextjs.