Setup
On first use, read
setup.md
for project integration.
When to Use
User needs Next.js expertise — routing, data fetching, caching, authentication, or deployment. Agent handles App Router patterns, server/client boundaries, and production optimization.
Architecture
Project patterns stored in
~/nextjs/
. See
memory-template.md
for setup.
~/nextjs/
├── memory.md # Project conventions, patterns
└── projects/ # Per-project learnings
Quick Reference
| Topic | File |
|---|
| Setup | setup.md
|
| Memory template | memory-template.md
|
| Routing (parallel, intercepting) | routing.md
|
| Data fetching & streaming | data-fetching.md
|
| Caching & revalidation | caching.md
|
| Authentication | auth.md
|
| Deployment | deployment.md
|
Core Rules
1. Server Components by Default
Everything is Server Component in App Router. Add
'use client'
only for useState, useEffect, event handlers, or browser APIs. Server Components can't be imported into Client — pass as children.
2. Fetch Data on Server
Fetch in Server Components, not useEffect. Use
Promise.all
for parallel requests. See
data-fetching.md
for patterns.
3. Cache Intentionally
fetch
is cached by default — use
cache: 'no-store'
for dynamic data. Set
revalidate
for ISR. See
caching.md
for strategies.
4. Server Actions for Mutations
Use
'use server'
functions for form submissions and data mutations. Progressive enhancement — works without JS. See
data-fetching.md
.
5. Environment Security
NEXT_PUBLIC_
exposes to client bundle. Server Components access all env vars. Use
.env.local
for secrets.
6. Streaming for Large Data
Use
<Suspense>
boundaries to stream content progressively. Wrap slow components individually. See
data-fetching.md
.
7. Auth at Middleware Level
Protect routes in middleware, not in pages. Middleware runs on Edge — lightweight auth checks only. See
auth.md
.
Server vs Client
| Server Component | Client Component |
|---|
| Default in App Router | Requires 'use client'
|
| Can be async | Cannot be async |
| Access backend, env vars | Access hooks, browser APIs |
| Zero JS shipped | JS shipped to browser |
Decision: Start Server. Add
'use client'
only for: useState, useEffect, onClick, browser APIs.
Common Traps
| Trap | Fix |
|---|
router.push
in Server | Use redirect()
|
<Link>
prefetches all | prefetch={false}
|
next/image
no size | Add width
/height
or fill
|
| Metadata in Client | Move to Server or generateMetadata
|
| useEffect for data | Fetch in Server Component |
| Import Server→Client | Pass as children/props |
| Middleware DB call | Call API route instead |
Missing await params
(v15) | Params are async in Next.js 15 |
Next.js 15 Changes
params
and searchParams
are now Promise
— must awaitfetch
not cached by default — opt-in with cache: 'force-cache'
- Use React 19 hooks:
useActionState
, useFormStatus
Related Skills
Install with
clawhub install <slug>
if user confirms:
react
— React fundamentals and patternstypescript
— Type safety for better DXprisma
— Database ORM for Next.js appstailwindcss
— Styling with utility classesnodejs
— Server runtime knowledge
Feedback
- If useful:
clawhub star nextjs
- Stay updated:
clawhub sync
