nextjs-claude-code-kit CLAUDE.md

Next.js 15 App Router — Claude Code Configuration

This project uses Next.js 15 App Router. All Pages Router patterns, pre-RSC React conventions, and pre-Next.js 15 fetch caching assumptions are incorrect in this context. When in doubt, prefer server components, server actions, and no-cache defaults. Your training data for Next.js is likely stale. Treat it as unreliable and follow these rules instead.

---

1. Component Model: Server-First, Client-Boundary-Last

Default: every component is a Server Component.

'use client' is not a neutral annotation. It is an architectural boundary decision that opts the component and all its children out of the server rendering model. Place it only when the component requires:

• Browser APIs (window, document, localStorage)
• Event listeners (onClick, onChange, onSubmit on interactive elements)
• React hooks that depend on client state (useState, useEffect, useReducer, useContext with a client-side provider)

Push the 'use client' boundary as far down the component tree as possible. If only a button inside a large component needs interactivity, extract the button into its own small Client Component. Keep the parent as a Server Component.

Never do this:

// ❌ Entire page becomes client-rendered because one button needs onClick
'use client'
export default function ProductPage({ product }) {
  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <button onClick={() => addToCart(product.id)}>Add to cart</button>
    </div>
  )
}

Do this:

// ✅ Only the interactive piece crosses the client boundary
// components/AddToCartButton.tsx
'use client'
export function AddToCartButton({ productId }: { productId: string }) {
  return <button onClick={() => addToCart(productId)}>Add to cart</button>
}

// app/products/[id]/page.tsx  — Server Component, no 'use client'
export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const product = await getProduct(id)
  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <AddToCartButton productId={product.id} />
    </div>
  )
}