claude-agent-kit: Skill for Claude Code

Next.js App Router Patterns

Modern patterns for Next.js 14+ with the App Router.

Server vs Client Components

Decision Guide

Use Server Components (default) when:

• Fetching data
• Accessing backend resources directly
• Keeping sensitive information on server (API keys, tokens)
• Large dependencies that shouldn't increase client bundle
• No interactivity needed

Use Client Components ('use client') when:

• Using React hooks (useState, useEffect, useContext)
• Adding event listeners (onClick, onChange)
• Using browser-only APIs
• Using custom hooks that depend on state/effects
• Using React Class components

Server Component (default)

// app/users/page.tsx
// No directive needed - Server Component by default

import { createClient } from '@/lib/supabase/server';

export default async function UsersPage() {
  const supabase = createClient();
  const { data: users } = await supabase.from('users').select('*');

  return (
    <div>
      <h1>Users</h1>
      <ul>
        {users?.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
}

Client Component

'use client';

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);

  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

Composition Pattern (Server + Client)

// app/dashboard/page.tsx (Server Component)
import { createClient } from '@/lib/supabase/server';
import { DashboardClient } from './DashboardClient';

export default async function DashboardPage() {
  const supabase = createClient();
  const { data: stats } = await supabase.from('stats').select('*');

  // Pass server data to client component
  return <DashboardClient initialStats={stats} />;
}

// app/dashboard/DashboardClient.tsx (Client Component)
'use client';

import { useState } from 'react';

export function DashboardClient({ initialStats }) {
  const [stats, setStats] = useState(initialStats);
  // Interactive logic here
}