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.
CODEBLOCK0
Quick Reference
| Topic | File |
|---|
| Setup | INLINECODE3 |
| 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 INLINECODE24 |
| 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 |
|---|
| INLINECODE26 in Server | Use INLINECODE27 |
| INLINECODE28 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 - INLINECODE39 not cached by default — opt-in with INLINECODE40
- Use React 19 hooks:
useActionState, INLINECODE42
Related Skills
Install with
clawhub install <slug> if user confirms:
- -
react — React fundamentals and patterns - INLINECODE45 — Type safety for better DX
- INLINECODE46 — Database ORM for Next.js apps
- INLINECODE47 — Styling with utility classes
- INLINECODE48 — Server runtime knowledge
Feedback
- - If useful: INLINECODE49
- Stay updated: INLINECODE50
设置
首次使用时，请阅读 setup.md 了解项目集成方式。
使用时机
用户需要 Next.js 专业知识——路由、数据获取、缓存、身份验证或部署。代理处理 App Router 模式、服务端/客户端边界以及生产环境优化。
架构
项目模式存储在 ~/nextjs/ 目录下。参见 memory-template.md 了解设置方式。
~/nextjs/
├── memory.md # 项目约定、模式
└── projects/ # 各项目学习记录
快速参考
memory-template.md |
| 路由（并行、拦截） | routing.md |
| 数据获取与流式传输 | data-fetching.md |
| 缓存与重新验证 | caching.md |
| 身份验证 | auth.md |
| 部署 | deployment.md |
核心规则
1. 默认使用服务端组件
App Router 中所有组件默认都是服务端组件。仅在需要使用 useState、useEffect、事件处理程序或浏览器 API 时添加 use client。服务端组件不能导入到客户端组件中——应作为 children 传递。
2. 在服务端获取数据
在服务端组件中获取数据，而不是在 useEffect 中。使用 Promise.all 进行并行请求。参见 data-fetching.md 了解相关模式。
3. 有意识地使用缓存
fetch 默认缓存——动态数据使用 cache: no-store。设置 revalidate 实现 ISR。参见 caching.md 了解策略。
4. 使用服务端操作处理数据变更
使用 use server 函数处理表单提交和数据变更。渐进增强——无需 JS 即可运行。参见 data-fetching.md。
5. 环境安全
NEXT
PUBLIC 会暴露给客户端打包文件。服务端组件可访问所有环境变量。使用 .env.local 存储密钥。
6. 大数据使用流式传输
使用
边界逐步流式传输内容。单独包裹慢速组件。参见 data-fetching.md。
7. 在中间件层进行身份验证
在中间件中保护路由，而不是在页面中。中间件在 Edge 上运行——仅进行轻量级身份验证检查。参见 auth.md。
服务端 vs 客户端
| 服务端组件 | 客户端组件 |
|---|
| App Router 默认 | 需要 use client |
| 可以是异步的 |
不能是异步的 |
| 可访问后端、环境变量 | 可访问 hooks、浏览器 API |
| 零 JS 发送 | JS 发送到浏览器 |
决策： 从服务端开始。仅在以下情况添加 use client：useState、useEffect、onClick、浏览器 API。
常见陷阱
| 陷阱 | 修复方法 |
|---|
| 在服务端使用 router.push | 使用 redirect() |
| <Link> 预获取所有内容 |
prefetch={false} |
| next/image 未设置尺寸 | 添加 width/height 或 fill |
| 在客户端使用元数据 | 移到服务端或使用 generateMetadata |
| 使用 useEffect 获取数据 | 在服务端组件中获取 |
| 将服务端组件导入客户端 | 作为 children/props 传递 |
| 中间件中调用数据库 | 改为调用 API 路由 |
| 缺少 await params（v15） | Next.js 15 中 params 是异步的 |
Next.js 15 变更
- - params 和 searchParams 现在是 Promise——必须 await
- fetch 默认不缓存——使用 cache: force-cache 选择启用
- 使用 React 19 hooks：useActionState、useFormStatus
相关技能
如果用户确认，使用 clawhub install 安装：
- - react — React 基础知识和模式
- typescript — 类型安全提升开发体验
- prisma — Next.js 应用的数据库 ORM
- tailwindcss — 使用工具类进行样式设计
- nodejs — 服务端运行时知识
反馈
- - 如果有用：clawhub star nextjs
- 保持更新：clawhub sync
