nextjs-guidelines（Next.js guidelines 开发）

Next.js App Router

Apply these patterns when building, reviewing, or debugging Next.js App Router applications.

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install nextjs

WHEN

• Building Next.js applications with App Router
• Migrating from Pages Router to App Router
• Implementing Server Components and streaming
• Setting up parallel and intercepting routes
• Optimizing data fetching and caching
• Building full-stack features with Server Actions
• Debugging hydration errors or RSC boundary issues

Rendering Modes

Server vs Client Decision Tree

Does it need...?
├── useState, useEffect, event handlers, browser APIs
│   └── Client Component ('use client')
├── Direct data fetching, no interactivity
│   └── Server Component (default)
└── Both?
    └── Split: Server parent fetches data → Client child handles UI

File Conventions

See file-conventions.md for complete reference.

app/
├── layout.tsx          # Shared UI wrapper (persists across navigations)
├── page.tsx            # Route UI
├── loading.tsx         # Suspense fallback (automatic)
├── error.tsx           # Error boundary (must be 'use client')
├── not-found.tsx       # 404 UI
├── route.ts            # API endpoint (cannot coexist with page.tsx)
├── template.tsx        # Like layout but re-mounts on navigation
├── default.tsx         # Parallel route fallback
└── opengraph-image.tsx # OG image generation

Route segments: [slug] dynamic, [...slug] catch-all, [[...slug]] optional catch-all, (group) route group, @slot parallel route, _folder private (excluded from routing).

Data Fetching Patterns

Choose the right pattern for each use case. See data-patterns.md for full decision tree.

Server Component Data Fetching (Preferred)

// app/products/page.tsx — Server Component by default
export default async function ProductsPage() {
  const products = await db.product.findMany() // Direct DB access, no API layer
  return <ProductGrid products={products} />
}

Avoiding Data Waterfalls

// BAD: Sequential — each awaits before the next starts
const user = await getUser()
const posts = await getPosts()

// GOOD: Parallel fetching
const [user, posts] = await Promise.all([getUser(), getPosts()])

// GOOD: Streaming with Suspense — each section loads independently
<Suspense fallback={<UserSkeleton />}><UserSection /></Suspense>
<Suspense fallback={<PostsSkeleton />}><PostsSection /></Suspense>

Server Actions (Mutations)

// app/actions.ts
'use server'
import { revalidateTag } from 'next/cache'

export async function addToCart(productId: string) {
  const cookieStore = await cookies()
  const sessionId = cookieStore.get('session')?.value
  if (!sessionId) redirect('/login')

  await db.cart.upsert({
    where: { sessionId_productId: { sessionId, productId } },
    update: { quantity: { increment: 1 } },
    create: { sessionId, productId, quantity: 1 },
  })
  revalidateTag('cart')
  return { success: true }
}

Caching Strategy

Invalidate from Server Actions:

'use server'
import { revalidateTag, revalidatePath } from 'next/cache'

export async function updateProduct(id: string, data: ProductData) {
  await db.product.update({ where: { id }, data })
  revalidateTag('products')   // Invalidate by tag
  revalidatePath('/products') // Invalidate by path
}

RSC Boundaries

Props crossing Server → Client boundary must be JSON-serializable. See rsc-boundaries.md.

Critical rule: Client Components cannot be async. Fetch data in a Server Component parent and pass it down.

Async APIs (Next.js 15+)

params, searchParams, cookies(), and headers() are all async. See async-patterns.md.

// Pages and layouts — always await params
type Props = { params: Promise<{ slug: string }> }

export default async function Page({ params }: Props) {
  const { slug } = await params
}

// Server functions
const cookieStore = await cookies()
const headersList = await headers()

// Non-async components — use React.use()
import { use } from 'react'
export default function Page({ params }: Props) {
  const { slug } = use(params)
}

Routing Patterns

Route Organization

Parallel Routes & Modals

See parallel-routes.md for complete modal pattern.

Key rules:

• Every @slot folder must have a default.tsx (returns null) or you get 404 on refresh
• Close modals with router.back(), never router.push() or <Link>
• Intercepting route matchers: (.) same level, (..) one level up, (...) from root

Metadata & SEO

See metadata.md for OG images, sitemaps, and file conventions.

// Static metadata (layout or page)
export const metadata: Metadata = {
  title: { default: 'My App', template: '%s | My App' },
  description: 'Built with Next.js',
}

// Dynamic metadata
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params
  const post = await getPost(slug)
  return {
    title: post.title,
    description: post.description,
    openGraph: { images: [{ url: post.image, width: 1200, height: 630 }] },
  }
}

Metadata is Server Components only. If a page has 'use client', extract metadata to a parent layout.

Error Handling

See error-handling.md for full patterns including auth errors.

// app/blog/error.tsx — must be 'use client'
'use client'
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Critical gotcha: redirect(), notFound(), forbidden(), and unauthorized() throw special errors. Never catch them in try/catch:

// BAD: redirect throw is caught — navigation fails!
try {
  await db.post.create({ data })
  redirect(`/posts/${post.id}`)
} catch (error) {
  return { error: 'Failed' } // Catches the redirect too!
}

// GOOD: Call redirect outside try-catch
let post
try { post = await db.post.create({ data }) }
catch (error) { return { error: 'Failed' } }
redirect(`/posts/${post.id}`)

Streaming with Suspense

export default async function ProductPage({ params }: Props) {
  const { id } = await params
  const product = await getProduct(id) // Blocking — loads first

  return (
    <div>
      <ProductHeader product={product} />
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews productId={id} />       {/* Streams in independently */}
      </Suspense>
      <Suspense fallback={<RecommendationsSkeleton />}>
        <Recommendations productId={id} /> {/* Streams in independently */}
      </Suspense>
    </div>
  )
}

Hooks That Require Suspense Boundaries

Performance

• Always use next/image over <img> — see image-optimization.md
• Always use next/link over <a> — client-side navigation with prefetching
• Always use next/font — see font-optimization.md
• Always use next/script — see scripts.md
• Set priority on above-the-fold images (LCP)
• Add sizes when using fill — without it, the largest image variant downloads
• Dynamic imports for heavy client components: const Chart = dynamic(() => import('./Chart'))
• Use generateStaticParams to pre-render dynamic routes at build time

Route Handlers

See route-handlers.md for API endpoint patterns.

Bundling

See bundling.md for fixing third-party package issues, server-incompatible packages, and ESM/CommonJS problems.

Hydration Errors

See hydration-errors.md for all causes and fixes.

Self-Hosting

See self-hosting.md for Docker, PM2, cache handlers, and deployment checklist.

Key points:

• Use output: 'standalone' for Docker — creates minimal production bundle
• Copy public/ and .next/static/ separately (not included in standalone)
• Set HOSTNAME="0.0.0.0" for containers
• Multi-instance ISR requires a custom cache handler (Redis/S3) — filesystem cache breaks
• Set health check endpoint at /api/health

NEVER Do

Reference Files