Articles/Claude Code

⟐ Claude Code/2026-04-06Advanced

Claude Code × Next.js 15 App Router Production: RSC, Server Actions, Auth, Testing & Deployment

The practical guide to production Next.js 15 App Router development with Claude Code. Covers RSC architecture decisions, Server Actions patterns, Auth.js v5, Vitest testing, and Cloudflare Workers deployment with practical code examples.

Claude Code²¹⁹ Next.js⁹ App Router³ React Server Components Server Actions TypeScript³⁴ Vercel Cloudflare Workers¹⁴

✦ Premium Article

Why Claude Code × Next.js 15 Transforms Production Development

Next.js 15's App Router, built around React Server Components (RSC), fundamentally changes how we think about web application architecture. It introduces powerful patterns for server-side rendering, data fetching, and streaming — but with that power comes increased complexity in managing server/client boundaries, cache invalidation strategies, and type safety across the stack.

Claude Code is the ideal pair programmer for navigating this complexity. Rather than just autocompleting code, it acts as a knowledgeable collaborator that understands your project's context, makes architectural recommendations, and generates production-ready implementations in seconds. In this guide, we'll walk through the real-world workflows and design patterns that make Claude Code + Next.js 15 such a powerful combination.

This guide is aimed at intermediate-to-advanced developers who already have a working knowledge of Next.js and TypeScript. We'll skip the basics and focus on the patterns that matter most in production.

Project Setup and Claude Code Configuration

Bootstrapping with the Right Defaults

Start with create-next-app and immediately configure Claude Code's project context:

npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"
 
cd my-app

Give Claude Code the following prompt to scaffold a production-ready setup in one shot:

Set up this Next.js 15 App Router project for production with:
- Drizzle ORM + PostgreSQL (type-safe DB layer)
- Auth.js v5 (authentication)
- Zod (runtime validation)
- Vitest (unit/component testing)
- Playwright (E2E testing)
- shadcn/ui (component library)
- Biome (fast ESLint + Prettier replacement)

Generate all configuration files and propose a src/ directory structure.

The CLAUDE.md File: Your Project's Persistent Context

Create CLAUDE.md at the project root. This file gives Claude Code the architectural constraints and conventions it needs to generate consistent, idiomatic code from day one:

# CLAUDE.md
 
## Project Overview
Next.js 15 App Router + TypeScript + Cloudflare Workers deployment
 
## Architecture Principles
- Default to Server Components; use 'use client' only for interactive parts
- Data fetching always happens in Server Components
- Client components receive only the minimum props needed for interactivity
- Server Actions handle all mutations and form submissions
- Validate all user input with Zod before processing
 
## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Files: kebab-case (user-profile.tsx)
- Types: PascalCase (UserType)
- Server functions: verb-first (getUser, createPost, deleteComment)
 
## Prohibited Patterns
- Never use useState/useEffect for data fetching
- Never call fetch() directly from client components
- Never expose sensitive data through component props
- No Node.js-specific APIs (fs, path, child_process) — Cloudflare Workers env

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Master RSC vs CSC design decisions and rapid implementation patterns with Claude Code guidance

✦Learn type-safe full-stack development combining Auth.js v5, Drizzle ORM, and Zod in a practical workflow

✦Understand the complete picture of production-quality testing and deployment automation with Vitest, Playwright, and Cloudflare Workers CI/CD

Secure payment via Stripe · Cancel anytime

App Router Architecture: Making RSC vs CSC Decisions

The Decision Framework

The most critical design decision in App Router development is deciding which components run on the server. When in doubt, ask Claude Code:

Help me decide: should each of these be RSC or CSC?
- User profile display (fetches from DB, no user interaction)
- Search form (shows real-time suggestions as user types)
- Product list (SSR initial load, client-side filtering)
- Like button (optimistic UI update + API mutation)

Here's the pattern in action:

// ✅ Server Component (default — no 'use client' needed)
// src/app/profile/page.tsx
import { db } from '@/lib/db'
import { users } from '@/lib/schema'
import { eq } from 'drizzle-orm'
 
export default async function ProfilePage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
 
  // Data fetching stays on the server — zero client-side bundle impact
  const user = await db.query.users.findFirst({
    where: eq(users.id, id),
    columns: {
      id: true,
      name: true,
      email: true,
      createdAt: true,
      // passwordHash is never selected — can't accidentally leak it
    },
  })
 
  if (!user) return <div>User not found</div>
 
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
      {/* Only the interactive part is a Client Component */}
      <FollowButton userId={user.id} />
    </div>
  )
}

// ✅ Client Component (only when necessary)
// src/components/follow-button.tsx
'use client'
 
import { useState, useTransition } from 'react'
import { followUser } from '@/app/actions/user'
 
export function FollowButton({ userId }: { userId: string }) {
  const [isFollowing, setIsFollowing] = useState(false)
  const [isPending, startTransition] = useTransition()
 
  const handleFollow = () => {
    startTransition(async () => {
      await followUser(userId)
      setIsFollowing(prev => !prev)
    })
  }
 
  return (
    <button
      onClick={handleFollow}
      disabled={isPending}
      className={isFollowing ? 'bg-gray-200' : 'bg-blue-500 text-white'}
    >
      {isPending ? 'Updating...' : isFollowing ? 'Following' : 'Follow'}
    </button>
  )
}

Streaming with Suspense

Next.js 15 lets you stream UI progressively using Suspense boundaries, so slow data fetches never block fast ones:

// src/app/dashboard/page.tsx
import { Suspense } from 'react'
import { UserStats } from '@/components/user-stats'
import { RecentActivity } from '@/components/recent-activity'
import { Recommendations } from '@/components/recommendations'
import { StatsSkeleton, ActivitySkeleton } from '@/components/skeletons'
 
// Each component streams independently
// A slow Recommendations fetch won't delay UserStats from rendering
export default function DashboardPage() {
  return (
    <div className="grid grid-cols-3 gap-4">
      <Suspense fallback={<StatsSkeleton />}>
        <UserStats />
      </Suspense>
 
      <Suspense fallback={<ActivitySkeleton />}>
        <RecentActivity />
      </Suspense>
 
      <Suspense fallback={<div>Loading recommendations...</div>}>
        <Recommendations />
      </Suspense>
    </div>
  )
}

Server Actions: Production-Grade Implementation Patterns

Type-Safe Server Actions with Zod

Server Actions are the backbone of App Router mutations. Combined with Zod and a discriminated union return type, they provide end-to-end type safety from the form to the database:

// src/app/actions/post.ts
'use server'
 
import { z } from 'zod'
import { auth } from '@/lib/auth'
import { db } from '@/lib/db'
import { posts } from '@/lib/schema'
import { revalidatePath } from 'next/cache'
 
const CreatePostSchema = z.object({
  title: z.string().min(1, 'Title is required').max(100, 'Max 100 characters'),
  content: z.string().min(10, 'Minimum 10 characters required'),
  published: z.boolean().default(false),
})
 
type ActionResult<T = void> =
  | { success: true; data: T }
  | { success: false; error: string; fieldErrors?: Record<string, string[]> }
 
export async function createPost(
  formData: FormData
): Promise<ActionResult<{ id: string }>> {
  const session = await auth()
  if (!session?.user?.id) {
    return { success: false, error: 'Authentication required' }
  }
 
  const result = CreatePostSchema.safeParse({
    title: formData.get('title'),
    content: formData.get('content'),
    published: formData.get('published') === 'true',
  })
 
  if (!result.success) {
    return {
      success: false,
      error: 'Validation failed',
      fieldErrors: result.error.flatten().fieldErrors,
    }
  }
 
  try {
    const [post] = await db.insert(posts).values({
      ...result.data,
      authorId: session.user.id,
      createdAt: new Date(),
      updatedAt: new Date(),
    }).returning({ id: posts.id })
 
    revalidatePath('/posts')
    if (result.data.published) revalidatePath('/')
 
    return { success: true, data: { id: post.id } }
  } catch (error) {
    console.error('Failed to create post:', error)
    return { success: false, error: 'Internal server error' }
  }
}

Optimistic Updates with useActionState

// src/components/create-post-form.tsx
'use client'
 
import { useActionState } from 'react'
import { createPost } from '@/app/actions/post'
 
const initialState = { success: false as const, error: '' }
 
export function CreatePostForm() {
  const [state, formAction, isPending] = useActionState(createPost, initialState)
 
  return (
    <form action={formAction}>
      <div>
        <label htmlFor="title">Title</label>
        <input id="title" name="title" type="text" />
        {!state.success && state.fieldErrors?.title && (
          <p className="text-red-500 text-sm">{state.fieldErrors.title[0]}</p>
        )}
      </div>
 
      <div>
        <label htmlFor="content">Content</label>
        <textarea id="content" name="content" rows={10} />
        {!state.success && state.fieldErrors?.content && (
          <p className="text-red-500 text-sm">{state.fieldErrors.content[0]}</p>
        )}
      </div>
 
      <label>
        <input type="checkbox" name="published" value="true" />
        Publish immediately
      </label>
 
      {!state.success && state.error && !state.fieldErrors && (
        <p className="text-red-500">{state.error}</p>
      )}
 
      <button type="submit" disabled={isPending}>
        {isPending ? 'Publishing...' : 'Publish Post'}
      </button>
    </form>
  )
}

Data Fetching Strategy: Avoiding Waterfalls

Request Memoization with React cache()

Next.js automatically deduplicates identical fetch() calls within a single request. For ORM queries (which don't use fetch()), wrap them in React.cache():

// src/lib/queries.ts
import { cache } from 'react'
import { db } from '@/lib/db'
import { users, posts } from '@/lib/schema'
import { eq } from 'drizzle-orm'
 
// Call this from multiple Server Components in the same request tree —
// only one DB query will execute
export const getUser = cache(async (id: string) => {
  return db.query.users.findFirst({
    where: eq(users.id, id),
  })
})
 
export const getUserPosts = cache(async (userId: string) => {
  return db.query.posts.findMany({
    where: eq(posts.authorId, userId),
    orderBy: (posts, { desc }) => [desc(posts.createdAt)],
    limit: 10,
  })
})

Parallel Fetching with Promise.all

// src/app/user/[id]/page.tsx
import { getUser, getUserPosts } from '@/lib/queries'
import { notFound } from 'next/navigation'
 
export default async function UserPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
 
  // Both queries fire simultaneously — no waterfall
  const [user, posts] = await Promise.all([
    getUser(id),
    getUserPosts(id),
  ])
 
  if (!user) notFound()
 
  return (
    <div>
      <h1>{user.name}</h1>
      <PostList posts={posts} />
    </div>
  )
}

Cache Strategy Design

// src/app/products/page.tsx
 
// Cache for 10 minutes (pricing doesn't change that often)
export const revalidate = 600
 
// For user-specific data that changes frequently
export const dynamic = 'force-dynamic'
 
// Pre-generate static paths at build time
export async function generateStaticParams() {
  const categories = await getCategories()
  return categories.map(cat => ({ category: cat.slug }))
}

Auth.js v5 Authentication

Setup and Session Configuration

// src/lib/auth.ts
import NextAuth from 'next-auth'
import GitHub from 'next-auth/providers/github'
import Google from 'next-auth/providers/google'
import { DrizzleAdapter } from '@auth/drizzle-adapter'
import { db } from '@/lib/db'
 
export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: DrizzleAdapter(db),
  providers: [
    GitHub({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),
    Google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
  session: { strategy: 'database' },
  callbacks: {
    // Extend session to include user ID and role
    session({ session, user }) {
      session.user.id = user.id
      session.user.role = user.role ?? 'user'
      return session
    },
  },
})

// src/app/api/auth/[...nextauth]/route.ts
import { handlers } from '@/lib/auth'
export const { GET, POST } = handlers

Middleware-Based Route Protection

// src/middleware.ts
import { auth } from '@/lib/auth'
import { NextResponse } from 'next/server'
 
export default auth((req) => {
  const { pathname } = req.nextUrl
 
  const protectedPaths = ['/dashboard', '/settings', '/admin']
  const isProtected = protectedPaths.some(path => pathname.startsWith(path))
 
  if (isProtected && !req.auth) {
    const signInUrl = new URL('/sign-in', req.url)
    signInUrl.searchParams.set('callbackUrl', pathname)
    return NextResponse.redirect(signInUrl)
  }
 
  if (pathname.startsWith('/admin') && req.auth?.user?.role !== 'admin') {
    return NextResponse.redirect(new URL('/403', req.url))
  }
 
  return NextResponse.next()
})
 
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
}

Testing Strategy: Vitest + Playwright

Unit and Component Testing with Vitest

// src/lib/queries.test.ts
import { describe, it, expect, beforeEach, vi } from 'vitest'
import { getUser } from './queries'
 
vi.mock('@/lib/db', () => ({
  db: {
    query: {
      users: { findFirst: vi.fn() },
    },
  },
}))
 
import { db } from '@/lib/db'
 
describe('getUser', () => {
  beforeEach(() => vi.clearAllMocks())
 
  it('returns user data when user exists', async () => {
    const mockUser = { id: '1', name: 'Test User', email: 'test@example.com' }
    vi.mocked(db.query.users.findFirst).mockResolvedValue(mockUser)
 
    expect(await getUser('1')).toEqual(mockUser)
    expect(db.query.users.findFirst).toHaveBeenCalledOnce()
  })
 
  it('returns undefined when user does not exist', async () => {
    vi.mocked(db.query.users.findFirst).mockResolvedValue(undefined)
    expect(await getUser('nonexistent')).toBeUndefined()
  })
})

// src/components/follow-button.test.tsx
import { render, screen, fireEvent, waitFor } from '@testing-library/react'
import { describe, it, expect, vi } from 'vitest'
import { FollowButton } from './follow-button'
 
vi.mock('@/app/actions/user', () => ({
  followUser: vi.fn().mockResolvedValue({ success: true }),
}))
 
describe('FollowButton', () => {
  it('toggles to following state on click', async () => {
    render(<FollowButton userId="user-1" />)
    fireEvent.click(screen.getByRole('button', { name: 'Follow' }))
    expect(screen.getByRole('button')).toBeDisabled()
    await waitFor(() => {
      expect(screen.getByRole('button', { name: 'Following' })).toBeInTheDocument()
    })
  })
})

End-to-End Testing with Playwright

// e2e/auth.spec.ts
import { test, expect } from '@playwright/test'
 
test.describe('Authentication flow', () => {
  test('unauthenticated users are redirected to sign-in', async ({ page }) => {
    await page.goto('/dashboard')
    await expect(page).toHaveURL(/\/sign-in/)
    await expect(page.locator('h1')).toContainText('Sign In')
  })
 
  test('authenticated users can access dashboard', async ({ page }) => {
    await page.goto('/sign-in')
    await page.fill('[name="email"]', process.env.TEST_USER_EMAIL!)
    await page.fill('[name="password"]', process.env.TEST_USER_PASSWORD!)
    await page.click('[type="submit"]')
    await expect(page).toHaveURL('/dashboard')
    await expect(page.locator('[data-testid="user-greeting"]')).toBeVisible()
  })
})

Performance Optimization: PPR and Image Optimization

Partial Pre-rendering (PPR)

Partial Pre-rendering, stabilized in Next.js 15, lets you combine static and dynamic content within a single route. The static shell is cached at the edge and served instantly, while dynamic content streams in afterward. Claude Code can help you identify which parts of your pages are good candidates for PPR.

// next.config.ts
const nextConfig = {
  experimental: {
    ppr: true, // Enable PPR globally
  },
}
 
export default nextConfig

// src/app/products/[id]/page.tsx
import { Suspense } from 'react'
import { ProductDetails } from '@/components/product-details'
import { PersonalizedRecommendations } from '@/components/personalized-recommendations'
import { StaticProductInfo } from '@/components/static-product-info'
 
// Static shell renders instantly from cache
// Dynamic parts stream in via Suspense
export default function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  return (
    <div>
      {/* Static: rendered at build time, served from edge cache */}
      <StaticProductInfo productId={params} />
 
      {/* Dynamic: real-time inventory, streams after static shell */}
      <Suspense fallback={<div>Loading inventory...</div>}>
        <ProductDetails productId={params} />
      </Suspense>
 
      {/* Personalized: session-dependent, streams last */}
      <Suspense fallback={<div>Loading recommendations...</div>}>
        <PersonalizedRecommendations productId={params} />
      </Suspense>
    </div>
  )
}

Ask Claude Code to analyze any page and suggest the optimal PPR boundaries: "Review this page component and identify which parts should be static shell vs dynamic Suspense boundaries for best performance."

Image Optimization Best Practices

Next.js's <Image> component provides automatic format conversion (WebP/AVIF), lazy loading, and layout shift prevention. Here's the production pattern with Claude Code:

// src/components/product-image.tsx
import Image from 'next/image'
 
interface ProductImageProps {
  src: string
  alt: string
  priority?: boolean // true for above-the-fold images
}
 
export function ProductImage({ src, alt, priority = false }: ProductImageProps) {
  return (
    <div className="relative aspect-square overflow-hidden rounded-lg">
      <Image
        src={src}
        alt={alt}
        fill
        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
        className="object-cover"
        priority={priority}
        // Next.js automatically generates srcset, converts to WebP/AVIF
        // and prevents cumulative layout shift
      />
    </div>
  )
}

For OGP images, use the built-in ImageResponse API from @vercel/og:

// src/app/articles/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og'
 
export const runtime = 'edge'
export const alt = 'Article thumbnail'
export const size = { width: 1200, height: 630 }
export const contentType = 'image/png'
 
export default async function OgImage({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const article = await getArticleBySlug(slug)
 
  return new ImageResponse(
    (
      <div
        style={{
          background: 'linear-gradient(135deg, #1a1a2e 0%, #16213e 100%)',
          width: '100%',
          height: '100%',
          display: 'flex',
          flexDirection: 'column',
          justifyContent: 'center',
          padding: '80px',
        }}
      >
        <div style={{ color: '#60a5fa', fontSize: 28, marginBottom: 20 }}>
          Claude Lab
        </div>
        <div
          style={{
            color: 'white',
            fontSize: 56,
            fontWeight: 700,
            lineHeight: 1.2,
          }}
        >
          {article?.title ?? 'Article'}
        </div>
      </div>
    ),
    { ...size }
  )
}

Bundle Analysis with Claude Code

When your bundle grows large, ask Claude Code to help diagnose it:

# Install bundle analyzer
npm install --save-dev @next/bundle-analyzer
 
# Add to next.config.ts
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})
 
# Run analysis
ANALYZE=true npm run build

Then share the bundle analysis output with Claude Code: "Here's my bundle analysis. Which dependencies are unusually large and what are the best alternatives or lazy-loading strategies?" Claude Code will give you specific recommendations for dynamic imports, tree-shaking improvements, and package alternatives.

Advanced Patterns: Metadata API and SEO

Dynamic Metadata Generation

// src/app/articles/[slug]/page.tsx
import type { Metadata } from 'next'
import { getArticleBySlug } from '@/lib/queries'
 
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>
}): Promise<Metadata> {
  const { slug } = await params
  const article = await getArticleBySlug(slug)
 
  if (!article) {
    return { title: 'Article Not Found' }
  }
 
  const ogImageUrl = `/articles/${slug}/opengraph-image`
 
  return {
    title: article.title,
    description: article.description,
    openGraph: {
      title: article.title,
      description: article.description,
      type: 'article',
      publishedTime: article.createdAt.toISOString(),
      authors: [article.author],
      images: [{ url: ogImageUrl, width: 1200, height: 630 }],
    },
    twitter: {
      card: 'summary_large_image',
      title: article.title,
      description: article.description,
      images: [ogImageUrl],
    },
    alternates: {
      canonical: `/articles/${slug}`,
    },
  }
}

Automatic Sitemap Generation

// src/app/sitemap.ts
import type { MetadataRoute } from 'next'
import { getAllArticles } from '@/lib/queries'
 
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const articles = await getAllArticles()
 
  const articleUrls = articles.map(article => ({
    url: `https://yoursite.com/articles/${article.slug}`,
    lastModified: article.updatedAt,
    changeFrequency: 'weekly' as const,
    priority: 0.8,
  }))
 
  return [
    {
      url: 'https://yoursite.com',
      lastModified: new Date(),
      changeFrequency: 'daily',
      priority: 1,
    },
    {
      url: 'https://yoursite.com/articles',
      lastModified: new Date(),
      changeFrequency: 'daily',
      priority: 0.9,
    },
    ...articleUrls,
  ]
}

Robots.txt Configuration

// src/app/robots.ts
import type { MetadataRoute } from 'next'
 
export default function robots(): MetadataRoute.Robots {
  return {
    rules: [
      {
        userAgent: '*',
        allow: '/',
        disallow: ['/api/', '/admin/', '/*?page='],
      },
    ],
    sitemap: 'https://yoursite.com/sitemap.xml',
  }
}

Cloudflare Workers Deployment Automation

OpenNext Configuration

// open-next.config.ts
import type { OpenNextConfig } from 'open-next/types/open-next'
 
const config: OpenNextConfig = {
  default: {
    override: {
      wrapper: 'cloudflare-node',
      converter: 'edge',
      incrementalCache: 'dummy',
      tagCache: 'dummy',
      queue: 'dummy',
    },
  },
  middleware: {
    external: true,
    override: {
      wrapper: 'cloudflare-edge',
      converter: 'edge',
    },
  },
}
 
export default config

GitHub Actions CI/CD Pipeline

# .github/workflows/deploy.yml
name: Deploy to Cloudflare Workers
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run test:unit
      - run: npm run build
      - run: npm run test:e2e
        env:
          TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
          TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
 
  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}

Common Pitfalls and How Claude Code Helps You Avoid Them

Even experienced developers run into App Router gotchas. Here are the most common ones and how Claude Code helps you navigate them.

Pitfall 1: "use client" Directive Propagation

When you mark a component 'use client', every component it imports also becomes a client component — even if those imported components don't need to be. This can accidentally push large dependencies into the client bundle.

The fix is to push 'use client' as far down the component tree as possible. Ask Claude Code: "Review my component tree and identify where I should move the 'use client' boundary to minimize client bundle size."

// ❌ Problematic: wraps everything in client boundary
'use client'
import { HeavyChart } from 'heavy-chart-library' // pulled to client
import { UserData } from '@/components/user-data'  // pulled to client
 
export function Dashboard() {
  const [filter, setFilter] = useState('weekly')
  return (
    <>
      <UserData />
      <HeavyChart filter={filter} onFilterChange={setFilter} />
    </>
  )
}
 
// ✅ Fixed: isolate the interactive part
// src/components/chart-controls.tsx
'use client'
export function ChartControls({ onFilterChange }: { onFilterChange: (f: string) => void }) {
  const [filter, setFilter] = useState('weekly')
  return (
    <select onChange={e => onFilterChange(e.target.value)}>
      <option value="weekly">Weekly</option>
      <option value="monthly">Monthly</option>
    </select>
  )
}
 
// src/app/dashboard/page.tsx — no 'use client' needed
import { UserData } from '@/components/user-data' // stays as RSC
import { HeavyChart } from 'heavy-chart-library'   // can use SSR version
import { ChartControls } from '@/components/chart-controls' // only this is CSC

Pitfall 2: Serialization Errors with Server Component Props

You can only pass serializable data from Server Components to Client Components. Functions, class instances, dates (in some contexts), and undefined values can cause serialization errors that are difficult to debug.

// ❌ Cannot pass a Date object directly — serialization error
<ClientComponent date={new Date()} />
 
// ✅ Serialize before passing
<ClientComponent dateIso={new Date().toISOString()} />
 
// ❌ Cannot pass a function from RSC to CSC props (it won't serialize)
<ClientComponent onAction={() => db.doSomething()} />
 
// ✅ Use a Server Action instead
import { doAction } from '@/app/actions'
<ClientComponent onAction={doAction} /> // Server Actions are serializable references

When you hit a serialization error, paste the error into Claude Code with context about your component structure. It will identify exactly which prop is causing the issue and suggest the correct fix.

Pitfall 3: Cache Invalidation Mismatches

revalidatePath() and revalidateTag() are powerful but easy to misuse. If you call revalidatePath('/posts') but your actual pages are at /posts/[slug], the root path revalidation may not cascade as expected.

// ✅ Revalidate both the list and the specific item
export async function updatePost(id: string, data: PostUpdateData) {
  await db.update(posts).set(data).where(eq(posts.id, id))
 
  // Revalidate the specific post page
  revalidatePath(`/posts/${id}`)
  // Revalidate the post list
  revalidatePath('/posts')
  // Revalidate homepage if featured posts appear there
  revalidatePath('/')
}
 
// Better: use tags for fine-grained control
export async function updatePost(id: string, data: PostUpdateData) {
  await db.update(posts).set(data).where(eq(posts.id, id))
  // Revalidate all pages tagged with this post's ID
  revalidateTag(`post-${id}`)
  revalidateTag('posts-list')
}

Ask Claude Code to audit your revalidatePath/revalidateTag calls: "Review all the Server Actions in this file and verify the cache revalidation strategy is correct and complete."

Pitfall 4: Missing Loading UI for Nested Layouts

Nested layouts in App Router can create unexpected loading states if you don't have loading.tsx files at each level. Users may see a blank screen or partial content flash.

app/
  layout.tsx
  loading.tsx          ← root loading
  dashboard/
    layout.tsx
    loading.tsx        ← dashboard loading (important!)
    analytics/
      page.tsx
      loading.tsx      ← analytics-specific loading

Claude Code can generate appropriate skeleton components for each level: "Generate a loading.tsx component that matches the layout structure of my dashboard page with appropriate skeleton placeholders."

Pitfall 5: TypeScript Types for Dynamic Route Params

In Next.js 15, route params are now Promises that must be awaited. This is a breaking change from Next.js 14 that catches many developers off guard.

// ❌ Next.js 14 style — breaks in Next.js 15
export default function Page({ params }: { params: { id: string } }) {
  // params.id works synchronously in 14, but causes type errors in 15
  return <div>{params.id}</div>
}
 
// ✅ Next.js 15 style
export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  return <div>{id}</div>
}

If you're migrating from Next.js 14 to 15, ask Claude Code: "Update all page and layout components in this directory to use the Next.js 15 async params pattern." It will systematically update every affected file.

Drizzle ORM Integration: Type-Safe Database Layer

Schema Definition and Migrations

Drizzle ORM is the recommended database layer for Next.js 15 production apps — it's fully TypeScript-native, works in edge environments, and has excellent Cloudflare D1 support.

// src/lib/schema.ts
import {
  pgTable,
  text,
  timestamp,
  boolean,
  uniqueIndex,
} from 'drizzle-orm/pg-core'
 
export const users = pgTable('users', {
  id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  role: text('role', { enum: ['user', 'admin'] }).default('user').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
})
 
export const posts = pgTable('posts', {
  id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
  title: text('title').notNull(),
  content: text('content').notNull(),
  slug: text('slug').notNull(),
  published: boolean('published').default(false).notNull(),
  authorId: text('author_id')
    .notNull()
    .references(() => users.id, { onDelete: 'cascade' }),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
}, table => ({
  slugIdx: uniqueIndex('posts_slug_idx').on(table.slug),
}))
 
// TypeScript infers these types automatically
export type User = typeof users.$inferSelect
export type NewUser = typeof users.$inferInsert
export type Post = typeof posts.$inferSelect
export type NewPost = typeof posts.$inferInsert

// src/lib/db.ts
import { drizzle } from 'drizzle-orm/node-postgres'
import { Pool } from 'pg'
import * as schema from './schema'
 
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,
})
 
export const db = drizzle(pool, { schema })

When you need complex queries, describe what you want in plain language to Claude Code and it will generate the optimal Drizzle query:

Write a Drizzle ORM query that:
- Gets all published posts with their author's name
- Filters by category if provided
- Supports cursor-based pagination (after postId)
- Returns only fields needed for the post list view
- Orders by most recent first

Looking back

Claude Code and Next.js 15 App Router combine into a genuinely powerful production development stack. The key takeaways:

RSC/CSC boundary: Keep data fetching server-side by default; pass only interactivity-required props to client components
Server Actions: Use the ActionResult<T> discriminated union with Zod for end-to-end type safety
Data fetching: Eliminate waterfalls with Promise.all and React.cache() memoization
Testing: Two-layer approach — Vitest for unit/component, Playwright for E2E
Deployment: GitHub Actions + Cloudflare Workers for zero-touch production deploys

Claude Code's real value isn't just knowing these patterns — it's being able to apply them correctly and consistently in your actual codebase. Set up CLAUDE.md with your project's constraints, be specific about what you're building, and treat it as the senior engineering partner it's designed to be.

For more on Node.js/TypeScript backend development with Claude Code, see the Claude Code × Node.js/TypeScript Backend Development Guide. For CI/CD automation deep dives, check out the Claude Code × HTTP Hooks CI/CD guide.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.