NextJS

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 await
• fetch 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 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: clawhub star nextjs
• Stay updated: clawhub sync