nextjs-server-client-components
Guide for choosing between Server Components and Client Components in Next.js App Router. CRITICAL for useSearchParams (requires Suspense + 'use client'), navigation (Link, redirect, useRouter), cookies/headers access, and 'use client' directive. Activates when prompt mentions useSearchParams, Suspe
By wsimmonds · 348 installs
npx skills add wsimmonds/claude-nextjs-skills --skill nextjs-server-client-components
Source repository · Upstream listing
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:
✅ CORRECT:
Common Next.js Type Patterns
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.
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.
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:
❌ WRONG Adding 'use client' to Server Component:
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:
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
Using searchParams
Access URL query parameters directly in Server Components:
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+):
CRITICAL PATTERN REQUIREMENT:
When extracting parameters from searchParams , ALWAYS use inline access to keep searchParams and the parameter name on the SAME LINE:
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):
Async params (Next.js 15+):
In Client Components:
Use hooks from next/navigation :
⚠️ 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:
❌ WRONG Missing 'use client':
❌ WRONG 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
Server Component passing promise:
Benefits of 'use' API
Enables parallel data fetching
Works with Suspense boundaries
Allows Server Components to pass promises to Client Components
Cleaner than prop drilling async data
Using 'use' with Context
Common Patterns
Pattern 1: Server Component Fetches, Client Component Interacts
Pattern 2: Parallel Data Fetching
Pattern 3: Streaming with Suspense
Pattern 4: Composition Server Inside Client
You CAN pass Server Components as children to Client Components:
Anti Patterns to Avoid
Anti Pattern 1: Using 'use client' Everywhere
Wrong:
Correct:
Why: Only use 'use client' when you actually need client side features. Static components should remain Server Components to reduce bundle size.
Anti Pattern 2: Fetching Data in Client Components
Wrong:
Correct:
Why: Server Components can fetch data directly, eliminating loading states and reducing client side JavaScript.
Anti Pattern 3: Accessing Server APIs in Client Components
Wrong:
Correct:
Why: cookies() , headers() , and other server only APIs can only be used in Server Components.
Anti Pattern 4: Serial Await (Waterfall)
Wrong:
Correct:
Why: Parallel fetching reduces total load time significantly.
Anti Pattern 5: Importing Server Component into Client Component
Wrong:
Correct:
Why: Importing a Server Component into a Client Component converts it to a Client Component. Pass it as children instead.
When Client Components ARE Appropriate
Client Components are the correct choice for:
1. Interactive Forms
2. Real Time Features
3. Browser Only Features
4. Third Party Libraries Requiring Window
5. React Context Providers
Quick Decision Tree
Testing Component Type
To verify component type:
Summary
Default to Server Components they're faster and more secure
Use Client Components only when you need interactivity or browser APIs
Never fetch data in Client Components with useEffect use Server Components
Pass promises to Client Components with React 'use' API
Access cookies/headers/searchParams only in Server Components
Use composition pattern to mix Server and Client Components
Fetch in parallel with Promise.all to avoid waterfalls