Scan to join WeChat groupDocuments the components.json schema (style, Tailwind config paths, aliases) and enforces using the detected package manager's runner (bunx/npx/pnpm dlx/yarn dlx) plus the shadcn MCP for CLI commands, never a manual component copy.
</objective>
shadcn Registries
Agent Workflow (MANDATORY)
Before registry configuration, spawn agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Find existing components.json
- fuse-ai-pilot:research-expert - Verify latest CLI options via Context7
After: Run fuse-ai-pilot:sniper for validation.
Overview
| Registry | Primitives | Style |
|----------|-----------|-------|
| @shadcn (default) | Base UI (default base since 2026-07-02) | base-* (e.g. base-nova) |
| @shadcn (default) | Radix UI | radix-* (e.g. radix-nova); legacy new-york (default deprecated) |
| @shadcn (default) | React Aria (since 2026-07-17) | aria-* |
| Directory registries (e.g. @basecn, Base UI) | Any | Built into the CLI, no config: add @basecn/<item> (list: ui.shadcn.com/docs/directory) |
| Custom namespace | Any | "registries": { "@acme": "https://.../{name}.json" } or registry add @acme=<url> |
| GitHub registry | Any | add owner/repo/item[#ref], root registry.json, no server/build |
Styles: {base}-{style} with base = base, radix, aria and style = vega, nova, maia, lyra, mira, luma, sera, rhea (schema: https://ui.shadcn.com/schema.json). Style cannot be changed after init; switch design with apply --preset instead.
Critical Rules
- ALWAYS detect PM before any CLI command (use {runner})
- ALWAYS consult MCP before adding components
- NEVER mix component bases (Base UI / Radix / React Aria) in same project
- KEEP components.json in sync with actual primitive
- USE CLI for adding components, never manual copy
- REVIEW third-party items before install:
view <item>,add <item> --dry-run|--diff|--view; pin GitHub items to a tag or full SHA
Architecture
project/
├── components.json # shadcn/ui configuration
├── components/ui/ # Generated components (import { cn } from "cn")
└── lib/utils.ts # export { cn } from "cn" (since Sept 2026; `migrate cn` for older projects)
-> See registry-setup.md for complete setup
CLI Commands
ALWAYS use detected package manager (run shadcn-detection first).
{runner} = bunx | npx | pnpm dlx | yarn dlx
# Initialize (alias: create). Default base = base (Base UI)
{runner} shadcn@latest init
{runner} shadcn@latest init -b radix # -b base | radix | aria (add -b radix in CI that expects Radix)
{runner} shadcn@latest init -t vite # -t next | start | vite | react-router | laravel | astro
{runner} shadcn@latest init --preset b2D0vQ7G4 --rtl --pointer --monorepo
{runner} shadcn@latest init --defaults # = --template=next + "nova" preset on the default base -> style base-nova
# Add components (resolved for the style in components.json)
{runner} shadcn@latest add button dialog select
{runner} shadcn@latest add button --dry-run # also --diff [path] (replaces deprecated `diff`), --view [path]
{runner} shadcn@latest add @basecn/button # directory registry, no config needed
{runner} shadcn@latest add acme/toolkit/auth-kit#v1.0.0 # GitHub registry item
# Presets and existing projects
{runner} shadcn@latest apply --preset b2D0vQ7G4 [--only theme,font] # keeps base + RTL
{runner} shadcn@latest preset decode|resolve|url|open <code>
{runner} shadcn@latest info --json # framework, base, style, aliases, installed components
{runner} shadcn@latest docs combobox --base aria # docs/examples/API links per base
# Discovery
{runner} shadcn@latest search @shadcn -q button -t ui --json # alias: list; no arg = all configured registries
{runner} shadcn@latest view @acme/auth acme/toolkit/item
# Maintenance
{runner} shadcn@latest migrate cn|icons|base-color|radix|rtl [path] # --list, --from, --to
{runner} shadcn@latest eject # inline shadcn/tailwind.css, drop the shadcn dependency (irreversible)
{runner} shadcn@latest mcp init --client claude # claude | cursor | vscode | codex | opencode
# Registry authoring
{runner} shadcn@latest build [./registry.json] -o ./public/r
{runner} shadcn@latest registry validate [./registry.json | owner/repo#ref]
{runner} shadcn@latest registry add @acme=https://acme.com/r/{name}.json
Flags above are from npx shadcn@4.21.0 <cmd> --help (2026-09-27). Details and sources: registry-config.md.
MCP (MANDATORY)
mcp__shadcn__search_items_in_registries -> find component
mcp__shadcn__get_add_command_for_items -> get exact CLI command
components.json Structure
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "base-nova",
"rsc": true,
"tailwind": { "config": "", "css": "app/globals.css", "baseColor": "neutral", "cssVariables": true },
"aliases": { "components": "@/components", "utils": "@/lib/utils" }
}
Schema-required keys: style, tailwind (config, css, baseColor, cssVariables), rsc, aliases (utils, components). Aliases may also be package.json#imports specifiers (#components, #lib/utils).
-> See registry-config.md for full schema
Reference Guide
Concepts
| Topic | Reference | When to Consult | |-------|-----------|-----------------| | Registry Config | registry-config.md | Setting up components.json |
Templates
| Template | When to Use | |----------|-------------| | registry-setup.md | Initial project setup |
Best Practices
DO
- Use MCP to check registry before adding
- Keep components.json in sync with actual primitive
- Use CLI for adding, not manual copy
DON'T
- Mix component bases in same project (Radix Combobox's
@base-ui/reactdependency is expected, not a mix) - Edit component internals without checking registry source
- Skip components.json configuration
- Install unpinned third-party GitHub items in published instructions