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]

[...slug]

[[...slug]]

(group)

@slot

_folder

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

fetch(url, { cache: 'no-store' })

fetch(url, { cache: 'force-cache' })

fetch(url, { next: { revalidate: 60 } })

fetch(url, { next: { tags: ['products'] } })

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.

string

number

boolean

'use server'

() => {}

Date

.toISOString()

Map

Set

Critical rule: Client Components cannot be

async

Async APIs (Next.js 15+)

params

searchParams

cookies()

headers()

// 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

(marketing)/

@analytics/

(.)photos/[id]

_components/

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'

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()

unauthorized()

// 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

useSearchParams()

usePathname()

useParams()

useRouter()

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.

window

localStorage

useEffect

new Date().toLocaleString()

useEffect

Math.random()

useId()

<p><div>...</div></p>

next/script

afterInteractive

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

'use client'

'use client'

async

Date

Map

redirect()

notFound()

unstable_rethrow()

loading.tsx

useSearchParams

<Suspense>

router.push()

router.back()

@vercel/og

next/og

default.tsx

default.tsx

null

sizes

fill

sizes="100vw"

<link>

next/font

Reference Files