21st-registry

21st レジストリで公開・管理する

コンポーネント、テーマ、テンプレートを 21st.dev に公開し、すでに公開したものを統一された 21st CLI（@21st-dev/cli）ですべて管理できます。

事前準備（必ず実施）

1. 公開前に認証してください。 コンポーネントの公開、一覧表示、チェックアウト、メタデータの編集、公開取り消しでは、21st login のセッションまたは 21st_sk_… API キーを使用できます。テーマ／テンプレートのコマンドでは、https://21st.dev/settings/api-keys で取得した実際の API キーを --api-key、TWENTYFIRST_TOKEN、または API_KEY_21ST で渡す必要があります。
2. CLI は統一された @21st-dev/cli（バイナリ 21st）です。独自に実装せず、これを使用してください。
3. 公開前に検索してください（21st search "<query>"）。ライブラリに重複した項目を追加しないようにします。

---

既存のコンポーネントと下書きを探す

ユーザーから以前のコンポーネント作業の続行や編集を依頼された場合は、ここから始めてください。

21st components
21st components --status draft --scope personal --json
21st open component:123
21st open draft:<uuid> --no-open

21st components は、デフォルトでページネーションされた 2 つのコレクションをそれぞれ最後まで取得するため、フィルターなしで実行すると、アクセス可能な個人または Team のすべてのコンポーネントと、所有するすべての下書きが返されます。--status all|draft|published|private または --scope all|personal|team:<uuid> で絞り込めます。返された安定した component:<id> または draft:<uuid> 参照を保持し、スラッグで置き換えないでください。

21st open draft:<uuid> は、編集可能な Studio の下書きを再開します。21st open component:<id> は、保持されている公開済みコンポーネントのコードとデモを基に、サーバー管理の CLI Review リビジョンを作成または再開します。そのリビジョンが公開されるまで、公開中のコンポーネントは変更されません。新しいカバー画像は必須です。任意の動画生成はバックグラウンドでベストエフォートで実行されます。--no-open を指定すると、ワークスペースを作成または再開して URL を表示しますが、ブラウザーは起動しません。

ソースがすでに変更されている場合は、ローカルファイルを使用してください。

21st publish ./Component.tsx \
  --component component:123 \
  --description "What changed"

安定した参照を、同じスラッグだろうという推測で置き換えないでください。コードをチェックアウトできるのは、元のコンポーネント作成者だけです。Team のマネージャーは、安定した参照を使ってチームメイトのコンポーネントのメタデータを編集したり、公開を取り消したりできます。

保持されているソース、依存関係、スタイル、サポートファイル、またはデフォルトのデモを安全に再現できない場合、チェックアウトは失敗します。チェックを緩めたり、コードにアクセスできると主張したりせず、上記のローカルソースコマンドを使用してください。

ログインセッションでは、個人の作業と、ユーザーが管理できる Teams を一覧表示できます。個人用キーでアクセスできるのは個人の項目のみです。一方、Team キーはその Team に制限されます。新しい CLI Review の下書きには、認証済みの個人または Team／ライブラリのスコープが保持されます。証明情報に基づいて復元された従来の CLI 下書きは、認証済みの該当スコープに戻されます。スコープを証明できない古い署名なしの下書きは、作り直しが必要な場合があります。

---

コンポーネントを公開する

位置引数のファイルパスから自動検出が実行されます。名前はエクスポートされたコンポーネントから、スラッグはファイル名から、タグはインポートから取得され、デモは自動検出または生成されます。新しいスラッグまたは所有するリビジョンの場合、コマンドは依存関係を検証し、コンポーネントをインストールしてビルドした後、Studio の下書きを作成し、専用の CLI Review を開いて完了を待ちます。レビューのサイドバーには正確な Demos (N) の件数が表示され、選択したデモがライブプレビューの横に表示されます。Studio はまず必須のカバー画像を生成し、その後、任意の動画をバックグラウンドで生成します。所有するリビジョンは、同じ CLI Review を完了して公開されるまで保留中のままです。

21st publish ./path/to/Component.tsx \
  --to default \
  --description "1-2 sentences: what it does and when to use it"

アクセスを決める — デフォルトは Published

ユーザーの要望…	フラグ
「公開して」「リンクを共有して」、または特に指定のない依頼	(なし — デフォルトは published)
「カタログに申請して」「注目枠に掲載して」	公開後、21st submit <slug> を実行
「Team のライブラリに限定して」「社内限定にして」	--private

公開で制御できるのはアクセスのみです。カタログへの掲載は必ず別途審査が必要なため、コンポーネントが公開されたからといって、自動的に申請されることはありません。

フラグのリファレンス

フラグ	使用するタイミング
--description "…"	必須。10 文字以上で、機能と使用するタイミングを記述します。内容を捏造せず、コードを読むかユーザーに確認してください。
--name、--slug、--tags a,b	自動検出された名前／URL スラッグ／1〜5 個のタグを上書きします。
--demo <file>	デモファイルです。自動検出されたファイル（{Comp}.demo.tsx、demos/{slug}.tsx、demos/default.tsx）を使用するか、簡単なものを合成します。実際のデモを指定すると、プレビューの品質が大幅に向上します。
--preview <img>	初期のカバー画像を設定します。生成されたカバー画像を置き換えますが、Studio のレビューや必須カバー画像の条件を回避することはできません。
--no-open	Studio の下書き URL を開かずに表示します。下書きは後でレビューできます。
--registry ui|hooks|blocks|icons	対象のサブレジストリ（デフォルトは ui）です。
--to <library-slug>	対象のチームライブラリです（例：--to default）。チームのデフォルトを使う場合は省略します。
--registry-dep <ref>	CLI Review ではまだサポートされていません。新しいコンポーネントまたは所有リビジョンを作成する前に削除してください。
--visibility published|private	アクセス範囲（デフォルトは published）です。

新しいスラッグまたは所有リビジョンの場合、コマンドは Studio の下書き URL を表示し、 Studio で公開された後にのみコンポーネント URL とインストールコマンドを表示します。 Ctrl+C を押すと、CLI の待機は停止しますが、下書きは保持されます。

デモに操作用コントロールを追加する（訪問者が操作できるノブパネル）

これを有効にするフラグはありません。コントロールはデモ自体のコードから生成されます。モジュールレベルの settings オブジェクトを 1 つ宣言し、デフォルトエクスポートで props を受け取るようにすると、公開パイプラインがプレビューの横に操作パネルを生成します。訪問者がノブを動かすと、「コードをコピー」で、その値が settings リテラルに反映されたコードが渡されます。そのため、設定可能なデモは静的なデモよりはるかに価値があります。調整可能な値があるものすべてに適用してください。粒子数、速度、色、サイズ、ラベル、機能フラグなどが該当します。

const settings = {
  particleCount: 1000,
  speed: 0.4,
  showGrid: true,
  glowColor: "#7dd3fc",
  palette: ["#0ea5e9", "#f472b6"],
  headline: "Ship faster",
}

export default function Demo(props: Partial<typeof settings>) {
  const s = { ...settings, ...props }
  return <Hero count={s.particleCount} speed={s.speed} ... />
}

両方が必要です。props がない settings（または settings がない props）ではパネルは表示されません。何も動かないノブは、ノブがないよりも悪いからです。

値ごとのコントロールは次のとおりです。ラベルと範囲は値から推測されます（particleCount →「Particle Count」）。

settings の値	コントロール
数値	スライダー（整数 -> 0..3x、0..1 の浮動小数点数 -> 比率スライダー）
boolean	スイッチ
CSS カラー文字列（#7dd3fc、oklch(...)）	カラーピッカー
カラー文字列の配列（12 個以下）	編集可能なパレット
その他の文字列、120 文字以下	テキストフィールド
ネストされたオブジェクト、混在した配列、長い文字列	なし — 代わりにトップレベルのキーにフラット化してください

オブジェクトを記述する前に知っておくべきルール：コントロールは最大 24 個です。キーは通常の識別子でなければならず、key、ref、constructor、prototype、__proto__ は使用できません。値はパイプラインが読み取れるリテラルでなければなりません（settings オブジェクト内でインポートした定数、計算式、スプレッド構文は使用できません）。Expo／ネイティブデモにはパネルが表示されません。

推測されたラベルと範囲はあくまで推定値であり、修正することを想定しています。CLI Review の Controls ブロックには、訪問者に表示されるパネルと同じものが表示されます。内容を確認し、公開前にラベルを変更して min/max/step を調整してください。編集しても値は変わりません。値は、実際に公開したコードから常に再読み込みされます。

新しいスラッグまたは所有するリビジョンの必須エージェントレビュー

ビルドゲートでは、宣言されていないパッケージ、インストールの失敗、解決されていないインポート、コンパイルエラーを検出します。ただし、レンダリングされた UI、インタラクション、色が視覚的に正しいことまでは確認できません。最終公開を許可する前に、次の手順を実施してください。

1. コンポーネントとデモを自己完結させます。インポートする npm パッケージはすべて最も近い package.json に宣言し、未解決のローカルインポートやエイリアスインポートを残さないでください。続行する前に、CLI ビルドが成功することを確認してください。現在の CLI コマンドでは、コンポーネントファイル 1 つとデモ 1 つのみが送信されます。追加のローカルファイルと 21st.json はまだ受け付けられません。
2. bg-primary、text-primary-foreground、bg-background、border-border など、移植性のある Tailwind のセマンティックトークンを使用します。カスタム CSS または任意のプロパティでは、var(--color-primary) や var(--color-muted-foreground) などの Tailwind v4 テーマ変数を使用してください。
3. oklch(var(--primary))、hsl(var(--primary)) を記述したり、--primary などの生の変数の保存形式を前提としたりしないでください。プロジェクトではチャンネルのタプルを保存し、Studio では完全な CSS 色を保存している場合があります。不透明度を設定するには、bg-primary/20 などのユーティリティか、var(--color-primary) を使った color-mix() を使用してください。
4. Studio を開いたら、専用の CLI Review を使用します。Demos (N) の数を確認し、すべてのデモを選択して、右側のライブプレビューを確認してください。意味のあるすべての状態を操作し、ライトテーマとダークテーマの両方を検証します。セマンティックなプライマリカラーが正しく解決されることも確認してください。デモで settings が宣言されている場合は、Controls パネルも操作してください。すべてのノブでプレビューが目に見えて変化し、ラベルと範囲が適切である必要があります。
5. プレビューが空白になる、エラーが発生する、依存関係が解決されない、または色が正しくない場合は、ソースを修正して 21st publish を再実行してください。プレビューを通過させるためだけに、ソースプロジェクトのブランドカラーをハードコードしないでください。
6. 最終公開の前に、自動生成される Cover を待ってください。カバー生成が最優先であり、カバーは公開に必須です。オプションの動画はバックグラウンドで可能な範囲で生成されます。公開が動画を待つことはなく、準備ができている場合のみ動画が含まれます。生成結果が実際の内容を適切に表していない場合は、どちらのアセットも手動で差し替えてください。 生成されたメディアは、ライブコンポーネントのレビューの代わりにはなりません。

コンポーネントの更新と新規作成

まずインベントリを確認してください。21st open component:<id> を使用して、保持されている公開済みコードとデモからレビュー済みリビジョンを作成するか、再開します。ソースがすでにローカルで変更されている場合は、代わりに 21st publish <file> --component component:<id> を実行してください。リビジョンの CLI Review が完了して公開されるまで、現在のライブバージョンは変更されません。ユーザーが新しいコンポーネントを意図していてもスラッグが競合する場合は、続行する前に確認し、別の --slug を提案してください。

エージェントの必須ルール

• 説明を捏造したり、API キー、シークレット、未保存の編集内容を含むファイルを公開したりしないでください。
• 既存の作業では、まずインベントリを確認し、安定した参照を使用してください。スラッグから推測しないでください。
• 必ず最初に検索し、役立つデモを用意し（調整可能な値がある場合は settings で操作できるようにします）、ビルドと依存関係を検証し、前述のライブプレビューとテーマトークンのレビューを完了し、最終公開の前に必須のカバーを待ってください。

---

テーマを公開する

テーマは CSS ファイルであり、トークン値を含む :root ブロックと .dark ブロックの両方を定義する必要があります。公開すると、コミュニティに公開されるテーマになります。

21st publish-theme ./my-theme.css --name "Midnight" [--tags dark,minimal]

手作業で作成する代わりに、現在のプロジェクトのデザイントークンからこの CSS を生成するには、21st-design-sync スキルを使用してください。

テンプレートを公開する

テンプレートはメタデータの一覧です（ファイルではなく URL）。モデレーションのために draft に登録されます。

21st publish-template "SaaS Starter" \
  --site https://demo.example.com \
  --preview https://example.com/thumb.png \
  [--description "…"] [--price 49] [--buy-url https://…] [--video https://…] [--tags 1,2]

---

公開済みのアイテムを編集・削除する

# Update an exact component from inventory. A Team manager may manage metadata.
21st edit component:<id> --type component --visibility published|private \
  [--description "…"] [--tags a,b]
21st edit <theme-id> --type theme [--visibility public|private] [--name "New Name"] [--tags a,b]
21st edit <template-id> --type template [--name N] [--description D] [--tags 1,2]

# Remove an item. ALWAYS requires --yes. Semantics differ by type:
#   component -> unpublished (visibility set to private; reversible via edit/re-publish)
#   theme     -> unpublished (removed from the marketplace; reversible)
#   template  -> PERMANENT hard delete
21st delete component:<id> --type component --yes
21st delete <id> --type theme|template --yes

# Catalog review is independent from Published/Private access.
21st submit <slug>
21st withdraw <slug>
21st resubmit <slug>
21st remove-from-catalog <slug>

注記：テンプレートの公開範囲はモデレーションによって管理されます（テンプレートでは --visibility は無視されます）。テーマの名前は --name で変更でき、public|private のみサポートしています。コンポーネントの編集・削除にはログインセッションまたは API キーを使用できますが、テーマ／テンプレートの管理には引き続き API キーが必要です。ブラウザーで編集する場合は、まず一覧を取得してから 21st open <stable-ref> を実行してください。保持されているコンポーネントのソースを安全にチェックアウトできない場合は、代わりに 21st publish <file> --component component:<id> を使って、レビュー済みのコードリビジョンを作成してください。

---

プロフィールページを管理する（ベントーボード）

21st.dev/@you の公開プロフィールには、従来のレイアウトの代わりに、ブロックを並べたベントースタイルのボードを表示できます。set は完全置換です（edit の --tags と同様です）。既存のコンテンツを残したい場合は、先に現在のボードを読み取ってください。

21st profile get [--json]                 # read your current board (as blocks)
21st profile set --file board.json        # replace it (JSON array, or pipe it via stdin)
21st profile set --clear                  # revert to the classic (non-bento) profile
21st profile upload ./cover.png           # upload a png/jpg/gif/webp, prints a url

board.json は上から順に並んだブロックの配列です。

[
  { "type": "component", "demoId": 143 },
  { "type": "library", "refId": "<personal-or-team-library-id>" },
  { "type": "social", "url": "https://x.com/you" },
  { "type": "note", "text": "Building UI for 21st.dev" },
  { "type": "hire", "headline": "Work with me", "url": "https://cal.com/you" },
  { "type": "divider" },
  { "type": "image", "mediaUrl": "<url from `profile upload`>" }
]

ブロックタイプ：component（自分自身の demoId。21st search --mine または 21st get で確認できます）、social（リンクカード。アイコンはドメインから自動検出されます）、note（テキスト）、hire／pro／support（headline/body/url/email/cta）、library（refId で指定する公開個人ライブラリまたはチームライブラリ）、image（profile upload の mediaUrl。外部 URL はエラーではなく破棄されます）、divider（ボードを新しいセクションに分割します）。すべてのブロックで、サイズ指定用の w／h（グリッド単位。幅は1～3、高さは1～2）を任意で指定できます。

並べ替えるには、ブロックの配列を希望する順序で再投稿します。ボードは配列の順序に従って、上から下、左から右へ配置されます。

チームと設定

21st teams                          # your teams
21st team <teamId>                  # a team's libraries
21st team-lists <teamId>            # a team's shared bookmark lists
21st team-components <teamId> [--library <id>]

21st init --client cursor|claude|codex|vscode|devin [--write]      # write MCP config