shadcn-impl-rsc-vs-client-boundaries

name	shadcn-impl-rsc-vs-client-boundaries
description	Use when wiring shadcn components into a Next.js App Router project, when deciding whether a given shadcn primitive needs a `"use client"` directive, when seeing the "Error: useState is not a function" or "Cannot read properties of null (reading useContext)" hydration errors from a Radix primitive in a server component, when designing the server-shell-plus-client-island layout for a page, when wrapping a context-providing library (next-themes, TanStack Query, jotai, zustand) for the App Router, or when the `rsc` field in `components.json` is set but the generated component file is still missing the directive. Prevents the over-clientification anti-pattern of marking the whole layout `"use client"` (defeats the streaming + RSC bundle savings of App Router), the missing-directive crash where a Radix-state component (Dialog, Select, Sidebar) renders on the server and throws `useState is not a function`, the forgotten Provider wrapper where next-themes ThemeProvider is imported directly into a server layout and crashes on hydration, the boundary-violation pattern where a server component tries to pass `onClick` or a class instance into a client child, and the unstable-directive anti-pattern of trying to apply `"use client"` conditionally or inline. Covers the per-primitive RSC compatibility matrix for the full evergreen-2026 component set (Card, Button, Badge, Alert, Skeleton, Separator, Label, Avatar, AspectRatio, Table, Typography are RSC-safe ; Dialog, Sheet, Drawer, Popover, Tooltip, HoverCard, Select, Combobox, Command, Form, Sonner, Tabs, Accordion, Carousel, Sidebar, Calendar, Toggle, Switch, Slider, Checkbox, Radio Group, Collapsible, ContextMenu, DropdownMenu, Menubar, NavigationMenu, ScrollArea require `"use client"`), the meaning and exact behaviour of `components.json` `rsc: true`, the file-level placement rule for the `"use client"` directive, the hybrid server-shell-plus-client-island composition pattern, the Provider-wrapper pattern (one-line `"use client"` wrapper around next-themes, TanStack Query, jotai), the rule that server components may pass a client component as `children` but not as an event-handler prop, and the serialisation requirement for any data crossing the boundary. Keywords: use client, "use client" directive, react server components, rsc, app router, Next.js server component, Next.js App Router, rsc:true components.json, where to put use client, server component cannot use hooks, server component hydration error, hydration mismatch, client boundary, RSC boundary, RSC compatibility, server component vs client component, server-component-cannot-pass-onclick, can I use Dialog in a server component, can I use shadcn Card in a server component, is Button server safe, ThemeProvider use client, next-themes use client, TanStack Query Provider use client, Sidebar server side, Form server side, Sonner Toaster server side, shadcn rsc flag, shadcn next.js, blank screen, app crashes on hydration, hydration error shadcn, useState is not a function, why is my dialog not opening on the server.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026, Next.js App Router (14+ / 15.x).
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui : RSC vs Client Boundaries

This skill is the rulebook for placing "use client" directives in a Next.js App Router project that consumes shadcn primitives. It covers which primitives are RSC-safe, which require the client boundary, where the directive belongs in the file tree, how the components.json rsc flag affects what the CLI emits, and how to build a page as a server shell that hosts small client islands.

Companion skills :

• shadcn-core-cli : components.json schema including the rsc flag.
• shadcn-impl-component-install : the install workflow that emits files with or without the directive.
• shadcn-syntax-form : the Form primitive (always client) and how it composes inside a server-rendered page.
• shadcn-syntax-dialog : the Dialog primitive (always client) and the Trigger+Content boundary patterns.
• shadcn-agents-rsc-boundary-validator (B14) : the automated validator that lints a project's "use client" placement against this matrix.

Quick Reference : The Boundary Rule

The "use client" directive marks the BOUNDARY, not the dependency.
Everything imported below a "use client" file is bundled for the client.
Everything above is server-only.

ALWAYS draw the boundary as DEEP in the tree as possible. NEVER mark a layout.tsx or page.tsx "use client" if a smaller leaf can carry the directive instead. The whole point of App Router is to ship less JavaScript ; a top-level "use client" defeats that.

ALWAYS : page.tsx (server) -> ClientIsland.tsx ("use client") -> Dialog
NEVER  : page.tsx ("use client") -> Dialog

Quick Reference : Per-Primitive Compatibility Matrix

The full 60-row matrix lives in references/methods.md. Top-line summary :

RSC-SAFE (no "use client" required, pure presentation) :
  Alert, AlertDialog content body, AspectRatio, Avatar, Badge, Breadcrumb,
  Button, Card, Empty, Field, Input, InputGroup, Item, Kbd, Label, Pagination,
  Separator, Skeleton, Spinner, Table primitives (Table/TableRow/...),
  Textarea, Typography elements.

CLIENT-REQUIRED ("use client" mandatory, uses Radix state / hooks / browser API) :
  Accordion, AlertDialog (root + trigger), Calendar, Carousel, Checkbox,
  Collapsible, Combobox, Command, ContextMenu, Dialog, Drawer,
  DropdownMenu, Form (react-hook-form), HoverCard, Input OTP, Menubar,
  Native Select (interaction states), NavigationMenu, Popover, Progress
  (animated variant), RadioGroup, Resizable, ScrollArea, Select, Sheet,
  Sidebar (uses useSidebar), Slider, Sonner (Toaster mount), Switch, Tabs,
  Toggle, ToggleGroup, Tooltip.