nextjs-server-client-components

# 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 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):** ```typescript // 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 <article>{post.title}</article>; } ``` **Async params (Next.js 15+):** ```typescript // 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 <article>{post.title}</article>; } ``` **In Client Components:** Use hooks from `next/navigation`: ```typescript // 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 ( <nav> <span>Current path: {pathname}</span> <span>Slug: {params.slug}</span> <span>Search: {searchParams.get('q')}</span> </nav> ); } ``` ### ⚠️ CRITICAL: useSearchParams ALWAYS Requires Suspense **When using `useSearchParams()` hook, you MUST:** 1. Add `'use client'` directive at the top of the file 2. Wrap the component in a Suspense boundary This is a **Next.js requirement** - failing to do both will cause errors. **✅ CORRECT Pattern:** ```typescript // app/page.tsx or any parent component import { Suspense } from 'react'; import SearchComponent from './SearchComponent'; export default function Page() { return ( <Suspense fallback={<div>Loading...</div>}> <SearchComponent /> </Suspense> ); } // app/SearchComponent.tsx 'use client'; import { useSearchParams } from 'next/navigation'; export default function SearchComponent() { const searchParams = useSearchParams(); const query = searchParams.get('q'); return <div>Search query: {query}</div>; } ``` **❌ WRONG - Missing 'use client':** ```typescript // This will fail - useSearchParams requires 'use client' import { useSearchParams } from 'next/navigation'; export default function SearchComponent() { const searchParams = useSearchParams(); // ERROR! return <div>{searchParams.get('q')}</div>; } ``` **❌ WRONG - Missing Suspense wrapper:** ```typescript // This will cause issues - useSearchParams requires Suspense export default function Page() { return <SearchComponent />; // Missing Suspense wrapper! } ``` ## React 'use' API for Promise Unwrapping The React `use` API allows reading promises and context in both Server and Client Components. ### Using 'use' with Promises ```typescript // app/components/UserProfile.tsx 'use client'; import { use } from 'react'; // IMPORTANT: Use specific types, generic types, or 'unknown' - NEVER 'any' // Option 1: Specific type (best when type is known) export default function UserProfile({ userPromise }: { userPromise: Promise<{ name: string; email: string }> }) { // Unwrap the promise const user = use(userPromise); return <div>{user.name}</div>; } // Option 2: Generic type (for reusable components) export function GenericDataDisplay<T>({ data }: { data: Promise<T> }) { const result = use(data);