21st-registry

21st チームライブラリでコンポーネントを公開・インストールする

このスキルは2つの用途で使用します。チーム向けにコンポーネントを公開する場合と、チームがすでに共有しているコンポーネントをインストールする場合です。

事前確認（必ず実施）

1. 認証を確認します。API_KEY_21ST 環境変数が設定されているか、レジストリ CLI に認証情報が保存されている必要があります。どちらも設定されていない場合は、ユーザーに npx @21st-dev/registry login を一度実行するよう伝えてください。こちらからログインを試みないでください。
2. CLI は @21st-dev/registry です。独自に作り直さず、これを使用してください。

---

コンポーネントの公開

公開範囲を決める — レジストリでは非公開リストをデフォルトにする

ユーザーの発言…	公開範囲
「チームと共有して」「チームにアップロードして」「社内向けに公開して」、または公開範囲が指定されていない依頼	選択した、またはデフォルトのレジストリで非公開リスト（公開範囲のフラグは不要）
「リンク経由で公開して共有して／プロフィールに掲載して。ただしライブラリには載せないで」	--unlisted
「一般公開して」「21st で公開して」	--public
「レジストリチームに限定して」「チーム内の非公開の下書きにして」	--private

ユーザーから明示的な指示がない限り、--public は絶対に使用しないでください。 公開コンポーネントは管理者のモデレーションを経て、21st ライブラリに掲載されます。共有可能な URL は必要だが、ライブラリには掲載したくない場合は、--unlisted が安全な選択肢です。

標準的な公開

CLI は位置引数のファイルパスから自動検出を行います。デフォルトエクスポートから名前を、ファイル名からスラッグを、インポートからタグを取得し、デモも自動検出または生成します。そのため、95％のケースでは以下で十分です。

npx @21st-dev/registry ./path/to/Component.tsx \
  --to default \
  --description "1-2 sentences about what it does and when to use it"

フラグのリファレンス

フラグ	使用するタイミング
--name "Display Name"	自動検出された名前を上書きします。デフォルトでは、デフォルトエクスポート名を人が読みやすい形式にした名前になります。
--description "…"	必須です。 10文字以上にしてください。機能と使用場面を説明する、実際の説明を記述してください。内容を捏造してはいけません。不明な場合はユーザーに確認してください。
--tags "form,input,validation"	小文字のタグを1～5個指定します。デフォルトではインポートから検出されます（lucide-react → "icon"、framer-motion → "animation" など）。自動検出されたタグが適切でない場合にのみ上書きしてください。
--slug my-button	URL のスラッグを上書きします。デフォルトでは名前からケバブケース形式で生成されます。
--demo ./Component.demo.tsx	デモファイルを指定します。次のパターンから自動検出されます：{Component}.demo.tsx、demos/{slug}.tsx、demos/default.tsx。どれも存在しない場合、CLI は自動的に簡単な <Component /> デモを生成します。v1 ではこれで問題ありませんが、実際のデモを用意するとプレビューの質が大幅に向上します。
--preview ./preview.png	任意です。 チームライブラリではライブ iframe プレビューを使用します。静止画像が必要なのは、すばやく表示できるサムネイルがほしい場合のみです。
--to <registry-slug>	認証済みチーム内の特定のレジストリを指定します（例：--to default）。省略すると、サーバーはチームの最初のレジストリ、またはデフォルトのレジストリを使用します。
--public / --unlisted / --private	コンポーネントの公開範囲を上書きします。

ユーザーに返される内容

✅ https://21st.dev/community/components/{username}/{slug}
Install in another project:
  npx @21st-dev/registry add @{username}/{slug}

既存コンポーネントの更新

同じコマンドで同じスラッグを指定すると、既存の内容が更新されます。CLI は「Published」ではなく「Updated」と表示します。バージョンフラグは不要です。チームメンバーには常に最新のものが提供されます。

ユーザーが「更新ではなく、新しいコンポーネントを作りたい」と言っているのにスラッグが重複する場合は、上書きする前にユーザーに確認してください。--slug の変更を提案してください。

コンポーネントのインストール

受け付けるアドレス形式は 2 つです。

• @team-slug/component-slug — チームレジストリからインストールします（チーム内で共有する場合に推奨）
• @username/component-slug — ユーザーの個人用／公開コンポーネントからインストールします

npx @21st-dev/registry add @acme/animated-button
# or
npx @21st-dev/registry add @serjobas/animated-button

CLI は次の処理を行います。

1. レジストリ JSON とコンポーネントファイルを取得します（サーバーは @handle をまず team-slug に照合し、次に username に照合します）
2. プロジェクトに書き込みます（デフォルトでは components/ui/{slug}.tsx）
3. npm 依存関係がある場合は pnpm/npm/yarn/bun add を実行します
4. 他の 21st コンポーネントに依存している場合は、それらを表示します — 別途 add でインストールしてください

shadcn を直接使用する場合、公開コンポーネントまたは非掲載コンポーネントには、プレーンなレジストリアイテム URL を使用できます。

npx shadcn@latest add "https://21st.dev/r/acme/animated-button"

繰り返しインストールする場合やプライベートコンポーネントの場合は、利用側プロジェクトの components.json に 21st レジストリを登録し、Bearer トークンを使用します。

{
  "registries": {
    "@YOUR_NAMESPACE": {
      "url": "https://21st.dev/r/acme/default/{name}.json",
      "headers": {
        "Authorization": "Bearer ${API_KEY_21ST}"
      }
    }
  }
}

その後、標準の shadcn CLI でインストールします。

npx shadcn@latest add @YOUR_NAMESPACE/animated-button

@YOUR_NAMESPACE は components.json で設定したローカルエイリアスにすぎません。分かりやすいスラッグを自由に選んでください。ユーザーがそのローカルファイルに個人用キーを含めることを明示的に希望している場合を除き、実際の API キーを components.json にコミットしないでください。

フラグ：

• --force — 既存のファイルを上書きします
• --no-install — npm のインストール手順をスキップします（ファイルの書き込みのみ）
• --dir PATH — 別のプロジェクトディレクトリにインストールします

---

チームライブラリの検索

ユーザーがコンポーネントを必要としているものの、正確な名前が分からない場合：

npx @21st-dev/registry search "<query>"

デフォルトのスコープは team（チームのライブラリ）です。自分のコンポーネントだけを検索するには --scope mine、公開ライブラリを検索するには --scope public を使用します。

似たコンポーネントがすでに存在する可能性がある場合は、公開前に必ず検索してください。 チームライブラリに重複して追加しないでください。

npx @21st-dev/registry search "button" --scope team
# Prints list with @user/slug refs you can pass to `add`.

---

チームとレジストリの管理

CLI からチームとレジストリの表示、作成、編集ができます（削除はできません。削除は Web Studio で行います）。各サブコマンドは --json を受け付けます。出力を解析する必要がある場合は、--json を優先してください。チームはスラッグで指定します（--team <slug>。デフォルトは API キーが属するチームです）。

# Inspect before acting
npx @21st-dev/registry team list --json            # all teams: slug, role, default
npx @21st-dev/registry team info [team]            # members + pending invites
npx @21st-dev/registry registry list --team <slug> --json

# Create
npx @21st-dev/registry team create "<name>" [--description TEXT]
npx @21st-dev/registry registry create "<name>" [--slug SLUG] [--description TEXT] [--team SLUG]
# registry slug is auto-derived from the name if --slug is omitted

# Edit
npx @21st-dev/registry team edit [team] --name TEXT --description TEXT   # owner only
npx @21st-dev/registry registry edit <slug> --name TEXT --description TEXT

# Invite a collaborator by email
npx @21st-dev/registry team invite <email> [--team SLUG]

新しいコンポーネントグループを公開する前の一般的な流れ：registry list --json で既存のものを確認 → 必要に応じて registry create "Marketing blocks" を実行 → publish --to marketing-blocks。

---

エージェントに関する厳守事項

• ❌ ユーザーから「公開して」と明示的に指示されていない限り、絶対に --public を使用しないでください。
• ❌ 説明を絶対に捏造しないでください。ユーザーに尋ねるか、コードを注意深く読んでください。
• ❌ 公開するコンポーネントファイルに API キー、環境変数の値、ハードコードされた内部 URL を絶対に含めないでください。
• ❌ 未保存の編集があるファイルを絶対に公開しないでください。先に変更を反映してください。
• ✅ 似たコンポーネントがすでに存在する可能性がある場合は、公開前に必ず検索してください。
• ✅ 可能であれば、現実的な props を使った有用なデモファイルを必ず追加してください。自動生成されたものを使うのは、最後の手段に限ります。

よくある間違いと回避方法

1. デモからのコンポーネントのインポートパスが間違っている。 CLI はアップロード前に相対インポート（例：import X from "../component"）を @/components/ui/{slug} に自動で書き換えます。そのため、デモではエイリアスではなく、ユーザーのソースファイルへの相対インポートを記述してください。あとは CLI が処理します。
2. 公開するたびにスラッグが変わる。 ユーザーがファイル名を変更すると、自動生成されるスラッグも変わり、重複が作成されます。安定した名前で再公開する場合は、--slug を明示的に指定してください。
3. コンポーネントに default export がない。 明確なエラーが表示されて失敗します。まず、コンポーネントを export default function ComponentName(...) にリファクタリングしてください。