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:

function handleSubmit(e: any) { ... } const data: any[] = [];

✅ CORRECT:

function handleSubmit(e: React.FormEvent) { ... } const data: string[] = [];

Common Next.js Type Patterns // Page props function Page({ params }: { params: { slug: string } }) { ... } function Page({ searchParams }: { searchParams: { [key: string]: string | string[] | undefined } }) { ... }

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

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

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

{data.map(product => (
• {product.name}
))}

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.

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

import { useState } from 'react';

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

return ( setCount(count + 1)}> Count: {count} ); }

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:

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

❌ WRONG - Adding 'use client' to Server Component:

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

Server Navigation Methods (NO 'use client' needed):

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:

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

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

Using searchParams

Access URL query parameters directly in Server Components:

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

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+):

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

CRITICAL PATTERN REQUIREMENT:

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

// ✅ 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 searchParams from parameter const params = await searchParams; // DON'T DO THIS const name = params.name; // searchParams not visible here

// ❌ WRONG: Destructuring (searchParams and name on same line but missing second 'name') const { name } = await searchParams; // Not preferred

Why inline access:

Keeps searchParams identifier visible on the same line as parameter extraction Makes the relationship between URL parameter and variable explicit Satisfies code review and testing patterns that check for proper searchParams usage Using pathname and Route Information

In Server Components (page.tsx):

// app/blog/[slug]/page.tsx export default async function BlogPost({ params, }: { params: { slug: string }; }) { // params contains route parameters const post = await getPost(params.slug);

return

Async params (Next.js 15+):

// app/blog/[slug]/page.tsx (Next.js 15+) export default async function BlogPost({ params, }: { params: Promise<{ slug: string }>; }) { const { slug } = await params; const post = await getPost(slug);

return

In Client Components:

Use hooks from next/navigation:

// app/components/Breadcrumbs.tsx 'use client';

import { usePathname, useParams, useSearchParams } from 'next/navigation';

export default function Breadcrumbs() { const pathname = usePathname(); // Current path: /blog/hello-world const params = useParams(); // Route params: { slug: 'hello-world' } const searchParams = useSearchParams(); // Query params

return (

⚠️ CRITICAL: useSearchParams ALWAYS Requires Suspense

When using useSearchParams() hook, you MUST:

Add 'use client' directive at the top of the file Wrap the component in a Suspense boundary

This is a Next.js requirement - failing to do both will cause errors.

✅ CORRECT Pattern:

// app/page.tsx or any parent component import { Suspense } from 'react'; import SearchComponent from './SearchComponent';

export default function Page() { return ( Loading...\