home / skills / hoangnguyen0403 / agent-skills-standard / server-components

server-components skill

safe

This skill guides Next.js Server and Client Components usage, clarifying server components, use client directive, and safe composition patterns for optimized

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill server-components

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.7 KB

---
name: Next.js Server Components
description: RSC usage, "use client" directive, and Component Purity.
metadata:
  labels: [nextjs, rsc, components]
  triggers:
    files: ['**/*.tsx', '**/*.jsx']
    keywords: [use client, Server Component, Client Component, hydration]
---

# Server & Client Components

## **Priority: P0 (CRITICAL)**

Next.js (App Router) uses React Server Components (RSC) by default.

## Server Components (Default)

- **Behavior**: Rendered on server, sent as HTML/Payload to client. Zero bundle size for included libs.
- **Capabilities**: Async/Await, Direct DB access, Secrets usage.
- **Restrictions**: No `useState`, `useEffect`, or Browser APIs (`window`, `localstorage`).

## Client Components

- **Directive**: Add `'use client'` at the VERY TOP of the file.
- **Usage**: Interactivity (`onClick`), State (`useState`), Lifecycle effects, Browser APIs.
- **Strategy**: Move Client Components to the leaves of the tree.
  - _Bad_: Making the root layout a Client Component.
  - _Good_: Wrapping a `<Button />` in a Client Component.

## Composition Patterns

- **Server-in-Client**: You cannot import a Server Component directly into a Client Component.
  - _Fix_: Pass Server Component as `children` prop to the Client Component.

```tsx
// ClientWrapper.tsx
'use client';
export default function ClientWrapper({ children }) {
  return <div>{children}</div>;
}

// Page.tsx (Server)
<ClientWrapper>
  <ServerComponent />
</ClientWrapper>;
```

## Anti-Patterns

- **Poisoning**: Importing server-only secrets into Client Components (Use `server-only` package to prevent).
- **Over-fetching**: Passing large data props to Client Components (Serialization cost). Only pass IDs if possible.

Overview

This skill explains Next.js Server Components (RSC), the 'use client' directive, and component purity patterns for App Router projects. It focuses on when to render on the server versus the client, how to compose components safely, and pitfalls to avoid. Follow these guidelines to minimize bundle size, secure secrets, and keep interactivity localized to client leaves.

How this skill works

Next.js App Router treats components as Server Components by default: they render on the server, can use async/await, access databases and secrets, and produce zero client bundle for included libs. To enable client-only behavior (state, effects, DOM APIs, event handlers), place 'use client' at the very top of the file; those components then run in the browser and add to the client bundle. Server components cannot be imported into client components directly; instead wrap server-rendered output as children of a client wrapper or pass minimal props (IDs) to fetch client-side if needed.

When to use it

Default to Server Components for data fetching, heavy CPU tasks, or secret usage.
Use 'use client' for interactive UI: event handlers, useState, useEffect, or direct DOM access.
Place client components at the leaves of the tree to limit bundle size and keep layouts server-rendered.
Use server components for direct DB access and server-only side effects.
Prefer passing IDs or small primitives to client components rather than large serialized objects.

Best practices

Keep 'use client' at the top of the file — otherwise the directive is ignored.
Avoid making root layouts client components; wrap only interactive parts as client leaves.
Do not import server-only secrets or server-only modules into client components; use the server-only package where appropriate.
Pass minimal data to client components — prefer IDs and fetch on the client if necessary to avoid over-fetching and serialization cost.
When composition requires mixing, render the server component inside a client wrapper via children rather than importing the server component into client code.

Example use cases

Server-render a dashboard with server components for data aggregation; use small client widgets for filters and controls.
Build a form that needs local validation and effects: create a client component for the form controls and keep the rest server-rendered.
Fetch sensitive data (secrets, DB) in server components and stream HTML to the client without exposing secrets.
Render lists server-side and pass item IDs to lightweight client components that handle per-item interactivity.

FAQ

What happens if I forget 'use client' placement?

If 'use client' is not the first statement, Next.js treats the file as a server component; client-only features will break or cause build errors.

Can client components access server-only secrets?

No. Client components run in the browser and cannot access server-only secrets. Keep secret access in server components or API routes.

How do I avoid large props to client components?

Pass IDs or small primitives and let the client fetch additional data, or perform data fetching in a server component and expose only what the client strictly needs.