shadcn-agents-rsc-boundary-validator

name	shadcn-agents-rsc-boundary-validator
description	Use when auditing a Next.js App Router codebase that consumes shadcn ui for misplaced or missing `"use client"` directives, when reviewing a pull request that adds shadcn primitives and you must confirm the boundary is correct before merging, when a build fails with the `useState is not a function` / `Cannot read properties of null (reading useContext)` Radix hydration crash, when `components.json` has been edited (toggled `rsc:true` <-> `rsc:false`, or added to a Vite / Astro / Pages-Router project where the flag must be `false`), when an AI-generated patch has slapped `"use client"` on `app/layout.tsx` or on every component file, when a Server Component tries to pass `onClick` / `onChange` / a class instance into a client child, when a Provider (next-themes ThemeProvider, TanStack Query QueryClientProvider, jotai Provider, zustand Provider, Sonner Toaster) has been imported directly into a server layout instead of through a thin client wrapper, or when a code-review checklist must enforce the RSC boundary rules before a release. Prevents the over-clientification anti-pattern of marking `app/layout.tsx` or `app/page.tsx` as `"use client"` (kills RSC for every descendant, defeats App Router bundle savings), the missing- directive crash where a file imports Dialog / Sheet / Drawer / Popover / Tooltip / HoverCard / Form / Select / Combobox / Command / Sonner / Tabs / Accordion / Carousel / Sidebar / Calendar without a `"use client"` header and Radix throws on render, the silently-ignored conditional directive (template literal `` `use client` ``, `if (...) "use client"`, comments before the directive) that the bundler treats as a normal string, the boundary-violation pattern where a server component passes an inline event handler into a client child, the forgotten Provider wrapper where next-themes / TanStack Query / Sonner is consumed directly in a server layout, the non-serialisable- prop crossing (Date with custom methods, Decimal, class instance, Map<string, classInstance>) that silently mis-renders after hydration, and the inverted-flag anti-pattern where `rsc:false` is set on an App Router project (every primitive ends up client) or `rsc:true` is set on a Vite project (primitives ship without the directive they need). Covers the validator workflow (scan file -> classify components -> verify directive presence + placement + form -> flag boundary violations -> report verdict), the 6-point project-level checklist (components.json `rsc` flag matches framework, every file-with- client-primitive has the directive, no `app/layout.tsx` carries the directive, no conditional or quoted-wrong directive, every Provider lives in a dedicated client wrapper file, no server-to-client function or class-instance prop), the per-primitive RSC compatibility matrix for the full 60-primitive evergreen-2026 catalogue (RSC-safe vs client-required vs mixed) inherited from the boundary skill, the grep patterns + ripgrep one-liners that flag each violation class, the worked validation scenarios (broken layout + missing Dialog directive vs corrected server-shell-plus-client-island), and the exact hand-off rules to the related shadcn skills. Keywords: rsc validator, validate use client, server component validator, boundary validator, components.json rsc check, layout use client warning, validate Next.js App Router shadcn, server passing onClick, validate Provider boundary, RSC code review, use client missing, use client conditional, hydration error validator, ThemeProvider in server layout, useState is not a function shadcn, useContext is null radix, server passes function to client, Dialog without use client, Sheet without use client, Form without use client, Sonner Toaster without use client, Sidebar without use client, rsc:true should be true, rsc:false on app router, rsc:true on vite, App Router shadcn audit, shadcn pr review, shadcn lint, why does my app crash on hydration, why is my dialog not opening, ship less javascript audit, smallest leaf use client, suppressHydrationWarning missing, non-serialisable prop, class instance prop crossing, …
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026, Next.js App Router (14+ / 15.x). For Vite, Astro, Remix, Pages Router the validator enforces `rsc:false`.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui : RSC Boundary Validator (Agent / Validator)

This skill is an AGENT skill. It does NOT teach how to compose RSC vs client trees (that is shadcn-impl-rsc-vs-client-boundaries, B10). It teaches an automated AUDIT : given a project tree, classify every shadcn import, verify the "use client" directive is in the right files, in the right form, in the right place, and that the boundary crossing follows the React Server Components rules.

ALWAYS run the validator as a six-point checklist in a fixed order. NEVER stop at the first failure ; a project usually has several boundary defects layered together, and the checklist surfaces all of them in one pass.

Companion Skills

• shadcn-impl-rsc-vs-client-boundaries (B10) : the rulebook that defines WHICH primitives need the directive and WHY ; this validator enforces those rules. The full per-primitive matrix lives in B10 references/methods.md (60 rows).
• shadcn-core-cli : components.json schema including the rsc flag, shadcn add --overwrite for regenerating a file whose directive is wrong.
• shadcn-impl-component-install : the install workflow that emits files with or without the directive ; use this skill if the validator reports a missing-directive file and you want to re-add cleanly.
• shadcn-impl-framework-integration : per-framework defaults (App Router -> rsc:true, Vite -> rsc:false, Astro client island -> rsc:false).

Quick Reference : Validator Workflow

INPUT  : a repo path with components.json + components/ui/* + app/ (or pages/)
PHASE 1 : scan components.json -> read `rsc` flag, detect framework
PHASE 2 : classify every file under components/ui/* and app/ using
          the per-primitive matrix (RSC-safe / client-required / mixed)
PHASE 3 : verify the `"use client"` directive is present where required,
          absent where forbidden, well-formed where present
PHASE 4 : scan for boundary-violation props (onClick / function / class
          instance passed from server file to client file)
PHASE 5 : scan for Provider-in-server-layout anti-pattern
PHASE 6 : emit a verdict report : PASS / WARN / FAIL with file + line
OUTPUT : 6-point checklist with PASS / FAIL per item + remediation hint

ALWAYS run all six phases even on small projects ; the cheap phases (grep) cost milliseconds and catch the silently-broken cases.

Quick Reference : 6-Point Checklist

[1] components.json `rsc` flag matches the framework :
    App Router -> rsc:true.
    Pages Router / Vite / Astro / Remix / TanStack Start -> rsc:false.

[2] Every file importing a CLIENT-REQUIRED primitive starts with the
    directive :
    Dialog / Sheet / Drawer / AlertDialog / Popover / Tooltip /
    HoverCard / Form / Select / Combobox / Command / Sonner (Toaster
    mount) / Tabs / Accordion / Carousel / Sidebar / Calendar /
    DropdownMenu / ContextMenu / Menubar / NavigationMenu / Switch /
    Slider / Checkbox / RadioGroup / Collapsible / ScrollArea /
    InputOTP / Toggle / ToggleGroup / Resizable / Chart / Progress.

[3] No `app/layout.tsx` / `app/page.tsx` / `app/template.tsx` carries
    the directive (defeats RSC for the whole subtree).

[4] Every `"use client"` is :
    - the FIRST non-whitespace / non-comment line of the file,
    - double-quoted or single-quoted (NEVER backticks, NEVER a
      template literal, NEVER inside an `if`),
    - file-level (no per-function or per-component attempt).

[5] Every context Provider (next-themes ThemeProvider, TanStack Query
    QueryClientProvider, jotai Provider, zustand Provider, Sonner
    Toaster, OverlayProvider, NuqsAdapter) lives in a dedicated
    `"use client"` wrapper file ; never imported directly into
    `app/layout.tsx` or any server component.

[6] No server file (no `"use client"` directive) passes a function
    (`onClick`, `onChange`, `onSubmit`, `onSelect`, ...) or a non-
    serialisable instance (class instance, Decimal, Date with custom
    methods, Map<key, classInstance>) to a client child.