nextjs-server-client-components

What this skill does

# Next.js Server Components vs Client Components

## Overview

Provide comprehensive guidance for choosing between Server Components and Client Components in Next.js App Router, including cookie/header access, searchParams handling, pathname routing, and React's 'use' API for promise unwrapping.

## TypeScript: NEVER Use `any` Type

**CRITICAL RULE:** This codebase has `@typescript-eslint/no-explicit-any` enabled. Using `any` will cause build failures.

**❌ WRONG:**
```typescript
function handleSubmit(e: any) { ... }
const data: any[] = [];
```

**✅ CORRECT:**
```typescript
function handleSubmit(e: React.FormEvent<HTMLFormElement>) { ... }
const data: string[] = [];
```

### Common Next.js Type Patterns

```typescript
// Page props
function Page({ params }: { params: { slug: string } }) { ... }
function Page({ searchParams }: { searchParams: { [key: string]: string | string[] | undefined } }) { ... }

// Form events
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => { ... }
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => { ... }

// Server actions
async function myAction(formData: FormData) { ... }
```

## When to Use This Skill

Use this skill when:
- Deciding whether to use Server or Client Components
- Accessing cookies, headers, or other server-side data
- Working with searchParams or route parameters
- Needing pathname or routing information
- Unwrapping promises with React 'use' API
- Debugging 'use client' boundary issues
- Optimizing component rendering strategy

## Core Decision: Server vs Client Components

### Default: Server Components

**All components in the App Router are Server Components by default.** No directive needed.

```typescript
// app/components/ProductList.tsx
// This is a Server Component (default)
export default async function ProductList() {
  const products = await fetch('https://api.example.com/products');
  const data = await products.json();

  return (
    <ul>
      {data.map(product => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}
```

**When to use Server Components:**
- Fetching data from APIs or databases
- Accessing backend resources (environment variables, file system)
- Processing sensitive information (API keys, tokens)
- Reducing client-side JavaScript bundle
- SEO-critical content rendering
- Static or infrequently changing content

**Benefits:**
- Zero client-side JavaScript by default
- Direct database/API access
- Secure handling of secrets
- Automatic code splitting
- Better initial page load performance
- Reduced bundle size

### Client Components: 'use client'

Add `'use client'` directive at the top of a file to make it a Client Component.

```typescript
// app/components/Counter.tsx
'use client';

import { useState } from 'react';

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

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

**When to use Client Components:**
- Need React hooks (useState, useEffect, useContext, etc.)
- Event handlers (onClick, onChange, onSubmit, etc.)
- Browser-only APIs (window, localStorage, navigator)
- Third-party libraries requiring browser environment
- Interactive UI elements (modals, dropdowns, forms)
- Real-time features (WebSocket, animations)

**Requirements for Client Components:**
- Must have `'use client'` directive at top of file
- Cannot use async/await directly in component
- Cannot access server-only APIs (cookies, headers)
- All imported components become Client Components

### ⚠️ CRITICAL: Server Components NEVER Need 'use client'

**Server Components are the DEFAULT. DO NOT add 'use client' unless you specifically need client-side features.**

**✅ CORRECT - Server Component with Navigation:**
```typescript
// app/page.tsx - Server Component (NO 'use client' needed!)
import Link from 'next/link';
import { redirect } from 'next/navigation';

export default async function Page() {
  // Server components can be async
  const data = await fetchData();

  if (!data) {
    redirect('/login');  // Server-side redirect
  }

  return (
    <div>
      <Link href="/dashboard">Go to Dashboard</Link>
      <p>{data.content}</p>
    </div>
  );
}
```

**❌ WRONG - Adding 'use client' to Server Component:**
```typescript
// app/page.tsx
'use client';  // ❌ WRONG! Don't add this to server components!

export default async function Page() {  // ❌ Will fail - async client components not allowed
  const data = await fetchData();
  return <div>{data.content}</div>;
}
```

**Server Navigation Methods (NO 'use client' needed):**
- `<Link>` component from `next/link`
- `redirect()` function from `next/navigation`
- Server Actions (see Advanced Routing skill)

**Client Navigation Methods (REQUIRES 'use client'):**
- `useRouter()` hook from `next/navigation`
- `usePathname()` hook
- `useSearchParams()` hook (also requires Suspense)

## Server Component Patterns

### Accessing Cookies

Use `next/headers` to read cookies in Server Components:

```typescript
// app/dashboard/page.tsx
import { cookies } from 'next/headers';

export default async function Dashboard() {
  const cookieStore = await cookies();
  const token = cookieStore.get('session-token');

  if (!token) {
    redirect('/login');
  }

  const user = await fetchUser(token.value);

  return <div>Welcome, {user.name}</div>;
}
```

**Important Notes:**
- `cookies()` must be awaited in Next.js 15+
- Cookies are read-only in Server Components
- To set cookies, use Server Actions (see Advanced Routing skill)
- Cookie access is only available in Server Components

### Accessing Headers

```typescript
// app/api/route.ts or any Server Component
import { headers } from 'next/headers';

export default async function Page() {
  const headersList = await headers();
  const userAgent = headersList.get('user-agent');
  const referer = headersList.get('referer');

  return <div>User Agent: {userAgent}</div>;
}
```

### Using searchParams

Access URL query parameters directly in Server Components:

```typescript
// app/search/page.tsx
export default async function SearchPage({
  searchParams,
}: {
  searchParams: { q?: string; category?: string };
}) {
  const query = searchParams.q || '';
  const category = searchParams.category || 'all';

  const results = await searchProducts(query, category);

  return (
    <div>
      <h1>Search Results for: {query}</h1>
      <p>Category: {category}</p>
      <ProductList products={results} />
    </div>
  );
}
```

**Important Notes:**
- `searchParams` is only available in `page.tsx` files
- In Next.js 15+, `searchParams` must be awaited
- searchParams is NOT available in `layout.tsx`
- Use client-side `useSearchParams()` hook if needed in Client Components

**⚠️ CRITICAL WARNING - Next.js 15+ searchParams:**
When extracting parameters in Next.js 15+, you MUST use destructuring to keep the `searchParams` identifier visible in the same line as the parameter extraction. Do NOT use intermediate variables like `params` or `resolved` - this is an anti-pattern that breaks code readability and testing patterns.

**Async searchParams (Next.js 15+):**

```typescript
// app/search/page.tsx (Next.js 15+)
export default async function SearchPage({
  searchParams,
}: {
  searchParams: Promise<{ q?: string }>;
}) {
  // BEST PRACTICE: Inline access keeps searchParams and parameter together on one line
  const q = (await searchParams).q || '';

  return <div>Search: {q}</div>;
}
```

**CRITICAL PATTERN REQUIREMENT:**

When extracting parameters from `searchParams`, **ALWAYS use inline access** to keep `searchParams` and the parameter name on the SAME LINE:

```typescript
// ✅ CORRECT: Inline access (REQUIRED PATTERN)
const name = (await searchParams).name || '';

// ✅ ALSO CORRECT: Multiple parameters
const category = (await searchParams).category || 'all';
const sort = (await searchParams).sort || 'asc';

// ❌ WRONG: Using intermediate variable separates searchP