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

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 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 for full schema

Reference Guide

Concepts

Templates

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