shadcn-registries

Configures shadcn/ui registries, `components.json`, and the shadcn CLI (4.21.0) — covering the default `@shadcn` registry (Base UI, Radix or React Aria styles, chosen with `init --base`), built-in directory registries such as `@basecn`, custom namespaced registries, GitHub registries (`owner/repo/item#ref`, public and private) and registry authoring (`include`, `registry validate`, dynamic search).

Documents 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.

shadcn Registries

Agent Workflow (MANDATORY)

Before registry configuration, spawn agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Find existing components.json
2. 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

1. ALWAYS detect PM before any CLI command (use {runner})
2. ALWAYS consult MCP before adding components
3. NEVER mix component bases (Base UI / Radix / React Aria) in same project
4. KEEP components.json in sync with actual primitive
5. USE CLI for adding components, never manual copy
6. 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 [email protected] <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/react dependency 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