shadcn-registries · diff
git:20260904.5f1d30f to git:20260927.43a351c
52 added, 17 removed. Audit A to A.
---
name: shadcn-registries
- description: "Use when configuring shadcn/ui registries, components.json, or CLI add/init commands."
+ description: "Use when configuring shadcn/ui registries (namespaced, GitHub, dynamic), components.json, presets, or any shadcn CLI command (init, add, apply, preset, view, search, docs, info, migrate, eject, build, registry)."
versions:
- shadcn-ui: "2.x"
+ shadcn-ui: "4.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.
+ 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.
</objective>
# 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) | Radix UI | `new-york`, `default` |
- | `@basecn` | Base UI | `base-vega` |
- | Custom | Any | Custom |
+ | `@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** registries in same project
+ 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
- └── lib/utils.ts # Utility functions (cn)
+ ├── 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](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`
```bash
- # Initialize
+ # Initialize (alias: create). Default base = base (Base UI)
{runner} shadcn@latest init
- {runner} shadcn@latest init --style new-york
+ {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 (default registry = Radix)
+ # 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
- # Add from Base UI registry
- {runner} shadcn@latest add --registry=basecn button dialog
+ # 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](references/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
```json
{
"$schema": "https://ui.shadcn.com/schema.json",
- "style": "new-york",
- "tailwind": { "config": "tailwind.config.ts", "css": "app/globals.css" },
+ "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](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
+ - 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