125k

GitHub レジストリ

PreviousNext

GitHub リポジトリをレジストリとして使います。

あらゆる GitHub リポジトリをレジストリにできます。

リポジトリのルートに registry.json ファイルを追加し、共有したいファイルを記述すれば、ユーザーは shadcn CLI でインストールできます。

pnpm dlx shadcn@latest add <username>/<repo>/<item>

レジストリサーバーを設定したり、生成した JSON ファイルを公開したりする必要はありません。GitHub リポジトリ自体がソースレジストリになります。

あらゆるファイルを配布する

レジストリ項目はコンポーネントや React コードに限定されません。 リポジトリ内のあらゆるファイルを含められます：ソースファイル、設定、ドキュメント、テンプレート、ワークフロー、ルール、プロジェクトの規約などです。

コンポーネント
components/date-picker.tsxcomponents/data-table.tsx
ヘルパーとユーティリティ
lib/format-date.tslib/cn.tshooks/use-copy.ts
デザインシステムパッケージ
tokens/colors.jsonstyles/theme.csscomponents/*
機能キット
app/(auth)/*lib/auth.tscomponents/login-form.tsx
エージェントのワークフロー
AGENTS.md.cursor/rules/*.claude/commands/*
プロジェクトの規約
.editorconfigbiome.jsondocs/conventions.md
Codemod と移行キット
codemods/*scripts/migrate.tsdocs/migration.md
テスト設定
vitest.config.tstest/setup.tsdocs/testing.md
CI とリリースのワークフロー
.github/workflows/ci.yml.github/workflows/release.yml
プロジェクトの自動化
scripts/release.tsscripts/checks.tsdocs/automation.md
Issue とプルリクエストのテンプレート
.github/ISSUE_TEMPLATE/*.github/pull_request_template.md
MCP 設定
.mcp.json.cursor/mcp.json

GitHub を使うべき場合

次のような場合に GitHub レジストリを使います：

  • GitHub リポジトリに再利用可能なコードがすでにある。
  • owner/repo/item から直接インストールしてほしい。
  • 同じリポジトリから設定ファイル、ルール、ドキュメント、テンプレート、ユーティリティ、その他のファイルを配布したい。
  • カスタムレジストリサーバーやリクエスト認証が必要ない。

要件

GitHub レジストリは次を満たす必要があります：

  • github.com のリポジトリであること。
  • リポジトリのルートに registry.json ファイルがあること。
  • 有効な registry.json と registry-item.json スキーマを使うこと。
  • リポジトリ内に存在するソースファイルを参照すること。

公開リポジトリは設定なしで動作します。プライベートリポジトリは GitHub の認証情報で動作します。プライベートリポジトリ をご覧ください。

GitHub Enterprise ホストは GitHub アドレスでは対応していません。リクエスト認証付きのカスタムレジストリサーバーを使う場合は、認証 付きの 名前空間 を使います。

ステップ1: registry.json の追加

既存のリポジトリがあるとします：

.
├── ...
├── .editorconfig
├── AGENTS.md
└── docs
    └── conventions.md

リポジトリのルートに registry.json を追加します。

.
├── ...
├── registry.json
├── .editorconfig
├── AGENTS.md
└── docs
    └── conventions.md

配布したい項目を定義します。

registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-toolkit",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "project-conventions",
      "type": "registry:item",
      "title": "Project Conventions",
      "description": "Shared project conventions, editor settings and agent instructions.",
      "files": [
        {
          "path": "AGENTS.md",
          "type": "registry:file",
          "target": "~/AGENTS.md"
        },
        {
          "path": ".editorconfig",
          "type": "registry:file",
          "target": "~/.editorconfig"
        },
        {
          "path": "docs/conventions.md",
          "type": "registry:file",
          "target": "~/docs/conventions.md"
        }
      ]
    }
  ]
}

ファイルをコミットしてプッシュします。

git add registry.json
git commit -m "add registry"
git push

ユーザーは GitHub から項目をインストールできるようになります。

pnpm dlx shadcn@latest add acme/toolkit/project-conventions

ステップ2: 任意のファイルを配布する

レジストリ項目は1つのファイルでも複数のファイルでもインストールできます。一緒に属するファイルは files 配列で宣言します。

たとえば、テスト設定では Vitest の設定ファイル、セットアップファイル、短いチームガイドをインストールできます。

registry.json
config
└── vitest.config.ts
docs
└── testing.md
test
└── setup.ts
registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-toolkit",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "vitest-setup",
      "type": "registry:item",
      "title": "Vitest Setup",
      "description": "A Vitest setup with project defaults and docs.",
      "files": [
        {
          "path": "config/vitest.config.ts",
          "type": "registry:file",
          "target": "~/vitest.config.ts"
        },
        {
          "path": "test/setup.ts",
          "type": "registry:file",
          "target": "~/test/setup.ts"
        },
        {
          "path": "docs/testing.md",
          "type": "registry:file",
          "target": "~/docs/testing.md"
        }
      ]
    }
  ]
}

ユーザーは同じ方法でインストールします。

pnpm dlx shadcn@latest add acme/toolkit/vitest-setup

ファイルを利用者のプロジェクト内の特定の場所に書き込む場合は target を使います。

registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-toolkit",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "editorconfig",
      "type": "registry:file",
      "files": [
        {
          "path": "config/.editorconfig",
          "type": "registry:file",
          "target": "~/.editorconfig"
        }
      ]
    }
  ]
}
pnpm dlx shadcn@latest add acme/toolkit/editorconfig

ステップ3: レジストリの検証

レジストリを共有する前に、CLI で検証します。

pnpm dlx shadcn@latest registry validate acme/toolkit

このコマンドはルートの registry.json を読み取り、include を解決し、レジストリ項目を検証して、参照先のファイルが存在するか確認します。

ブランチ、タグ、コミット SHA を指定して検証することもできます。

pnpm dlx shadcn@latest registry validate acme/toolkit#v1.0.0

ステップ4: 項目の一覧表示と検索

list を使ってリポジトリレジストリ内のすべての項目を表示します。

pnpm dlx shadcn@latest list acme/toolkit

search を使ってカタログを絞り込みます。

pnpm dlx shadcn@latest search acme/toolkit --query conventions

view を使って1つの項目ペイロードを確認します。

pnpm dlx shadcn@latest view acme/toolkit/project-conventions

include で整理する

大規模なリポジトリでは、項目定義を説明対象のソースファイルの近くに置きます。

registry.json
config
├── prettier.config.mjs
└── registry.json
rules
├── agent.md
└── registry.json

ルートの registry.json からネストされたレジストリファイルを取り込めます。

registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-toolkit",
  "homepage": "https://github.com/acme/toolkit",
  "include": ["config/registry.json", "rules/registry.json"]
}

取り込まれるレジストリファイルでは、そのディレクトリ用の項目を宣言します。

rules/registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "items": [
    {
      "name": "agent-rules",
      "type": "registry:file",
      "files": [
        {
          "path": "agent.md",
          "type": "registry:file",
          "target": "~/AGENTS.md"
        }
      ]
    }
  ]
}

include を使う場合、ファイルパスは項目を宣言している registry.json ファイルからの相対パスになります。

pnpm dlx shadcn@latest add acme/toolkit/project-conventions

レジストリの依存関係

あるレジストリ項目が別のレジストリ項目に依存する場合は registryDependencies を使います。

同じリポジトリ内の依存関係

同じ GitHub リポジトリ内の依存関係には、完全な GitHub 項目アドレスを使います。

registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-toolkit",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "project-setup",
      "type": "registry:item",
      "registryDependencies": [
        "acme/toolkit/agent-rules",
        "acme/toolkit/prettier-config",
        "acme/toolkit/tsconfig"
      ],
      "files": [
        {
          "path": "docs/project-setup.md",
          "type": "registry:file",
          "target": "~/docs/project-setup.md"
        }
      ]
    }
  ]
}

ドキュメント項目は、同じリポジトリのテンプレート項目に依存できます。

registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-toolkit",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "contributing-guide",
      "type": "registry:item",
      "registryDependencies": ["acme/toolkit/readme-template"],
      "files": [
        {
          "path": "docs/contributing.md",
          "type": "registry:file",
          "target": "~/docs/contributing.md"
        }
      ]
    }
  ]
}

CI 設定は、ユーザーが個別にインストールできるのと同じ整形・テストの既定値に依存できます。

registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-toolkit",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "ci-setup",
      "type": "registry:item",
      "registryDependencies": [
        "acme/toolkit/prettier-config",
        "acme/toolkit/vitest-setup"
      ],
      "files": [
        {
          "path": ".github/workflows/ci.yml",
          "type": "registry:file",
          "target": "~/.github/workflows/ci.yml"
        }
      ]
    }
  ]
}

外部レジストリへの依存関係

項目は外部レジストリに依存することもできます。依存先を所有するレジストリの完全な項目アドレスを使います。

registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-toolkit",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "workspace-setup",
      "type": "registry:item",
      "registryDependencies": [
        "@acme/tsconfig",
        "contoso/devtools/prettier-config"
      ],
      "files": [
        {
          "path": "docs/workspace.md",
          "type": "registry:file",
          "target": "~/docs/workspace.md"
        }
      ]
    }
  ]
}

依存関係の ref

Ref は依存関係をまたいで継承されません。依存関係をピン留めしたい場合は、その依存関係自体に ref を含めます。

registry.json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "acme-toolkit",
  "homepage": "https://github.com/acme/toolkit",
  "items": [
    {
      "name": "project-setup",
      "type": "registry:item",
      "registryDependencies": [
        "acme/toolkit/agent-rules#v1.0.0",
        "acme/toolkit/tsconfig#c0ffee254729296a45d6691db565cf707a3fef5d"
      ],
      "files": [
        {
          "path": "docs/project-setup.md",
          "type": "registry:file",
          "target": "~/docs/project-setup.md"
        }
      ]
    }
  ]
}

便利なコマンド

GitHub レジストリ内のすべての項目を一覧表示します。

pnpm dlx shadcn@latest list acme/toolkit

GitHub レジストリを検索します。

pnpm dlx shadcn@latest search acme/toolkit -q conventions

GitHub レジストリを検証します。

pnpm dlx shadcn@latest registry validate acme/toolkit

GitHub レジストリから項目をインストールします。

pnpm dlx shadcn@latest add acme/toolkit/project-conventions

GitHub レジストリの項目を表示します。

pnpm dlx shadcn@latest view acme/toolkit/project-conventions

レジストリ項目名に / を含む項目をインストールします。

pnpm dlx shadcn@latest add acme/toolkit/rules/agent

タグからインストールします。

pnpm dlx shadcn@latest add acme/toolkit/project-conventions#v1.0.0

完全なコミット SHA からインストールします。

pnpm dlx shadcn@latest add acme/toolkit/project-conventions#c0ffee254729296a45d6691db565cf707a3fef5d

Ref

ブランチ、タグ、コミット SHA からインストールするには #ref を使います。

pnpm dlx shadcn@latest add acme/toolkit/project-conventions#main

Ref にはスラッシュを含められます。

pnpm dlx shadcn@latest add acme/toolkit/project-conventions#feature/conventions

ref を指定しない場合、CLI はリポジトリの既定ブランチを使います。

CLI はファイルを読み取る前に、Git を使ってブランチ、タグ、短い ref をコミット SHA に解決します。40文字の完全なコミット SHA は直接使われ、Git は必要ありません。

プライベートリポジトリ

プライベートな github.com リポジトリもレジストリとして動作します。サーバーを設定したり、レジストリ側で何かを構成したりする必要はありません。リポジトリを読み取れれば、CLI はそこからインストールできます。

GitHub CLI を使う

ローカル開発では、GitHub CLI で一度認証します：

gh auth login

他の GitHub レジストリと同じように、プライベートリポジトリからインストールします。

pnpm dlx shadcn@latest add acme/private-toolkit/project-conventions

リポジトリが公開読み取りできない場合、CLI は保存済みの認証情報を使って gh 経由で読み取ります。トークンは GitHub CLI 内に留まります。shadcn プロセスに入ることはありません。

認証情報を初めて使うコマンドでは、次の通知が表示されます：

✔ Using gh credentials.

CI でトークンを使う

GitHub CLI がインストールされていない環境では、GH_TOKEN または GITHUB_TOKEN を設定します：

GH_TOKEN=github_pat_xxx npx shadcn@latest add acme/private-toolkit/project-conventions
  • GH_TOKEN は GITHUB_TOKEN より優先されます。
  • リポジトリにスコープされたきめ細かい個人アクセストークンを使い、Contents: Read-only アクセスを付けます。これが推奨される認証情報です。
  • トークンが設定されている場合は GitHub CLI の代わりに使われ、api.github.com にのみ送信されます。

仕組み

  • 公開リポジトリは常に匿名で読み取られます。認証情報は使われず、GitHub CLI が呼び出されることもありません。
  • CLI はまず匿名アクセスを試みます。リポジトリのルートの registry.json が公開読み取りできない場合にのみ認証情報を使います。
  • ref の解決はまず git ls-remote を実行します。Git は、たとえば gh auth setup-git でインストールされたものなど、構成済みの認証情報ヘルパーをすでに使っている場合があります。
  • プライベートファイルは GitHub の Contents API 経由で読み取られ、解決済みのコミット SHA にピン留めされます。
  • GitHub はプライベートリポジトリと存在しないリポジトリに同じ not-found 応答を返します。認証情報でもリポジトリを読み取れない場合、CLI はどちらの場合か判断できません。

制限事項

  • レジストリのソースファイルは1ファイルあたり5 MiB までに制限されます。
  • GitHub Enterprise ホストには対応していません。GitHub アドレスは常に github.com に対して解決されます。
  • レジストリのソースファイルではシンボリックリンクを避けてください。匿名読み取りではシンボリックリンクのターゲットパスがテキストとして返され、Contents API 経由の認証読み取りではターゲットファイルの内容が返されます。

インストール前の確認

GitHub レジストリ項目は GitHub リポジトリからコードやプロジェクトファイルをインストールします。GitHub 項目アドレスは他のサードパーティ製コード依存関係と同じように扱います。

管理していないソースからインストールする前に：

  • リポジトリとルートの registry.json を確認します。
  • 項目定義、特に files、target、dependencies、devDependencies、registryDependencies、envVars を確認します。
  • 外部レジストリへの依存関係を確認します。他のレジストリからファイルをインストールする場合があります。
  • 公開するインストールコマンドにはピン留めした ref を使います。40文字の完全なコミット SHA が最も再現性の高い選択肢です。
  • インストール前に shadcn view acme/toolkit/project-conventions で解決済みの項目ペイロードを確認します。
  • 項目の確認に支援がほしい場合は、shadcn view の出力をエージェントやレビューツールに渡します。
  • ファイルを書き込まずにインストールをプレビューするには shadcn add acme/toolkit/project-conventions --dry-run を使います。
  • 適用前にファイルの変更や内容を確認するには、shadcn add に --diff や --view を付けて使います。