wsimmonds/claude-nextjs-skills/nextjs-server-client-components

Claude Code and agent skill by wsimmonds/claude-nextjs-skills

Trust tier 3
  • community
  • ext:[{"type":"context","description":"Custom context provider definitions"}]
Source check pending

Checking that the SKILL.md file is still in the repository.

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, Suspense, navigation, routing, Link component, redirect, pathname, searchParams, cookies, headers, async components, or 'use client'. Essential for avoiding mixing server/client APIs.

Install

npx vskill@latest install wsimmonds/claude-nextjs-skills/nextjs-server-client-components

Semi-extensibleMentions customization, but needs skill-specific knowledge. Read the extensible skills standard

SKILL.md

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>;
}

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
74
Repository forks
9
7-day trend score
22

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 16 Mar 2026, 7 months ago.

Extension points

  • contextCustom context provider definitions

Learn the extensible skills standard

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/wsimmonds/claude-nextjs-skills/nextjs-server-client-components/badge)](https://verified-skill.com/skills/wsimmonds/claude-nextjs-skills/nextjs-server-client-components)

Something wrong with this skill or its page? Tell us.