shadcn-registries

shadcn/ui レジストリ、`components.json`、shadcn CLI（4.21.0）を構成します — デフォルトの `@shadcn` レジストリ（Base UI、Radix、React Aria スタイル。`init --base` で選択）、`@basecn` などの組み込みディレクトリレジストリ、カスタム名前空間レジストリ、GitHub レジストリ（`owner/repo/item#ref`、公開および非公開）、レジストリの作成（`include`、`registry validate`、動的検索）を扱います。

components.json スキーマ（style、Tailwind 設定パス、エイリアス）を説明し、CLI コマンドには検出されたパッケージマネージャーのランナー（bunx/npx/pnpm dlx/yarn dlx）と shadcn MCP を使用することを徹底し、手動でのコンポーネントコピーは決して行いません。

shadcn レジストリ

エージェントワークフロー（必須）

レジストリの構成前に、name を指定した Agent 呼び出しを1つずつ使い、エージェントを並列で起動します。

1. fuse-ai-pilot:explore-codebase - 既存の components.json を検索する
2. fuse-ai-pilot:research-expert - Context7 経由で最新の CLI オプションを確認する

その後: 検証のために fuse-ai-pilot:sniper を実行します。

---

概要

レジストリ	プリミティブ	スタイル
@shadcn（デフォルト）	Base UI（2026-07-02 以降のデフォルトベース）	base-*（例: base-nova）
@shadcn（デフォルト）	Radix UI	radix-*（例: radix-nova）。レガシーの new-york（default は非推奨）
@shadcn（デフォルト）	React Aria（2026-07-17 以降）	aria-*
ディレクトリレジストリ（例: @basecn、Base UI）	任意	CLI に組み込み、設定不要: add @basecn/<item>（一覧: ui.shadcn.com/docs/directory）
カスタム名前空間	任意	"registries": { "@acme": "https://.../{name}.json" } または registry add @acme=<url>
GitHub レジストリ	任意	add owner/repo/item[#ref]、ルートの registry.json、サーバー/ビルド不要

スタイル: {base}-{style}。base = base、radix、aria、style = vega、nova、maia、lyra、mira、luma、sera、rhea（スキーマ: https://ui.shadcn.com/schema.json）。スタイルは init 後に変更できません。代わりに apply --preset でデザインを切り替えてください。

---

重要なルール

1. 常に PM を検出してから CLI コマンドを実行する（{runner} を使用）
2. コンポーネントを追加する前に常に MCP を参照する
3. 同じプロジェクト内でコンポーネントのベース（Base UI / Radix / React Aria）を決して混在させない
4. components.json を実際のプリミティブと同期させ続ける
5. コンポーネントの追加にはCLI を使用し、手動コピーは決して行わない
6. インストール前にサードパーティの項目を確認する: view <item>、add <item> --dry-run|--diff|--view。GitHub の項目はタグまたは完全な SHA にピン留めする

---

アーキテクチャ

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)

-> 完全なセットアップについては registry-setup.md を参照してください

---

CLI コマンド

常に検出されたパッケージマネージャーを使用してください（先に shadcn-detection を実行）。 {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

上記のフラグは npx [email protected] <cmd> --help（2026-09-27）によるものです。詳細と出典: registry-config.md。

MCP（必須）

mcp__shadcn__search_items_in_registries -> find component
mcp__shadcn__get_add_command_for_items  -> get exact CLI command

---

components.json の構造

{
  "$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" }
}

スキーマで必須のキー: style、tailwind（config、css、baseColor、cssVariables）、rsc、aliases（utils、components）。エイリアスは package.json#imports の指定子（#components、#lib/utils）にすることもできます。

-> 完全なスキーマについては registry-config.md を参照してください

---

リファレンスガイド

概念

トピック	リファレンス	参照すべきタイミング
レジストリ設定	registry-config.md	components.json をセットアップするとき

テンプレート

テンプレート	使用するタイミング
registry-setup.md	初期プロジェクトセットアップ

---

ベストプラクティス

推奨

• 追加前に MCP を使ってレジストリを確認する
• components.json を実際のプリミティブと同期させ続ける
• 追加には手動コピーではなく CLI を使用する

やってはいけないこと

• 同じプロジェクト内でコンポーネントのベースを混在させる（Radix Combobox の @base-ui/react 依存は想定内であり、混在ではありません）
• レジストリのソースを確認せずにコンポーネントの内部を編集する
• components.json の設定をスキップする
• 公開されている手順に、バージョン固定されていないサードパーティの GitHub アイテムをインストールする