/shadcn-registries

name: shadcn-registries
description: "Use when configuring shadcn/ui registries, components.json, or CLI add/init commands."
versions:
  shadcn-ui: "2.x"
  shadcn-cli: "latest"
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, mcp__shadcn__search_items_in_registries, mcp__shadcn__view_items_in_registries, mcp__shadcn__get_add_command_for_items
references: references/registry-config.md, references/templates/registry-setup.md
related-skills: shadcn-components, shadcn-detection

<objective> Configures shadcn/ui registries, `components.json`, and CLI init/add commands — covering the default `@shadcn` (Radix UI) registry, the `@basecn` (Base UI) registry, and custom registries.

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. </objective>

shadcn Registries

Agent Workflow (MANDATORY)

Before registry configuration, use `TeamCreate`:

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) | Radix UI | `new-york`, `default` | | `@basecn` | Base UI | `base-vega` | | Custom | Any | Custom |

---

Critical Rules

1. **ALWAYS detect PM** before any CLI command (use {runner}) 2. **ALWAYS consult MCP** before adding components 3. **NEVER mix** registries in same project 4. **KEEP** components.json in sync with actual primitive 5. **USE CLI** for adding components, never manual copy

---

Architecture

project/
├── components.json         # shadcn/ui configuration
├── components/ui/          # Generated components
└── lib/utils.ts            # Utility functions (cn)

-> See [registry-setup.md](references/templates/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
{runner} shadcn@latest init
{runner} shadcn@latest init --style new-york

# Add components (default registry = Radix)
{runner} shadcn@latest add button dialog select

# Add from Base UI registry
{runner} shadcn@latest add --registry=basecn button dialog

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": "new-york",
  "tailwind": { "config": "tailwind.config.ts", "css": "app/globals.css" },
  "aliases": { "components": "@/components", "utils": "@/lib/utils" }
}

-> See [registry-config.md](references/registry-config.md) for full schema

---

Reference Guide

Concepts

| Topic | Reference | When to Consult | |-------|-----------|-----------------| | **Registry Config** | [registry-config.md](references/registry-config.md) | Setting up components.json |

Templates

| Template | When to Use | |----------|-------------| | [registry-setup.md](references/templates/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 registries in same project
• Edit component internals without checking registry source
• Skip components.json configuration