GitHubでブロックレジストリを公開する
よいブロックをいくつか作ったら、次のプロジェクトでも使いたくなるでしょう。
テーマ間でフォルダーを手作業でコピーすると、コピーごとの差が大きくなり、修正版がどのテーマにあるのか誰も分からなくなります。各ブロックを独自のビルド工程が必要なパッケージにするのも、block.jsonとテンプレートを含むフォルダーには大げさです。
その中間にあるのがブロックレジストリです。これはregistry.jsonファイルとブロックフォルダーの集合で、通常のHTTP経由で配信されます。利用側がCLIコマンドを実行すると、ブロックのソースがテーマにコピーされ、その後は利用側がそのコピーを管理します。GitHubリポジトリがあればレジストリをホストできます。GitHubは公開リポジトリ内のすべてのファイルをraw URLで配信するためです。
このガイドでは、4つのブロックを含むacmeというレジストリを構築し、acme/acme-blocksリポジトリから公開します。そこからテーマにブロックをインストールし、gitタグでリリースを固定します。
npm上のblockstudioパッケージはバージョン0.0.1です。このリリースはプレースホルダーで、唯一のコマンドであるaddはAdding block: <name>を表示して、何も取得せずに終了します。このガイドのコマンドと出力は、Blockstudioリポジトリ(packages/registry)にあるレジストリCLIからのもので、レジストリのドキュメントで説明されているCLIです。
各要素の連携
知っておくべきファイルは2つです:
registry.jsonはブロックの作者が公開します。ブロックの一覧、各ブロックを構成するファイル、ダウンロード元のbaseUrlを記載します。blocks.jsonは利用側のテーマまたはプラグインに配置します。使用するレジストリと、ブロックのインストール先ディレクトリを指定します。
ブロックをインストールすると、CLIはblocks.jsonにある各レジストリを取得し、ブロックを見つけて依存関係を解決します。次に、記載された各ファイルを{baseUrl}/{block}/{file}からダウンロードして{directory}/{block}/{file}に書き込みます。変換処理は行わないため、ディスク上のファイルはリポジトリ内のファイルと完全に同じです。
手順1: リポジトリを構成する
ルートにregistry.jsonを置き、blocks/の下にブロックごとのフォルダーを配置したリポジトリを作成します:
acme-blocks/
registry.json
blocks/
hero/
block.json
index.php
card/
block.json
index.php
style.scss
tabs/
block.json
index.php
style.scss
tab-item/
block.json
index.php
フォルダー名はレジストリ内のブロック名になり、利用側のテーマでもフォルダー名として使われます。block.json内のブロック名の後半部分(hero/にあるacme/hero)と同じ名前にすると、インストール後のフォルダーを見分けやすくなります。
手順2: ブロックを作成する
各フォルダーは通常のBlockstudioブロックです。ヒーローブロックにはフィールドが1つあります:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"category": "design",
"blockstudio": {
"attributes": [
{
"id": "heading",
"type": "text",
"label": "Heading",
"default": "Build faster"
}
]
}
}
<section useBlockProps class="acme-hero">
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>
cardも同じパターンに従い、style.scssを追加します。tabsは<InnerBlocks allowedBlocks='["acme/tab-item"]' />を描画し、tab-itemは"parent": ["acme/tabs"]を宣言するため、tabsはtab-itemがないと役に立ちません。次の手順で、この関係をレジストリに記述します。
これらのブロックにレジストリ固有の要素はありません。CLIはフォルダーをコピーするため、@wordpress/create-blockで作成したブロックも、通常のPHPで登録したブロックも、同じ方法で公開できます。
手順3: registry.jsonを記述する
registry.jsonには、すべてのブロックと、CLIがダウンロードするすべてのファイルを記載します:
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "acme",
"description": "Acme block library.",
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
"blocks": [
{
"name": "hero",
"title": "Hero",
"description": "Full-width hero section with a heading.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
},
{
"name": "card",
"title": "Card",
"description": "Content card with a title.",
"category": "components",
"type": "blockstudio",
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": ["block.json", "index.php", "style.scss"]
},
{
"name": "tab-item",
"title": "Tab Item",
"description": "Single tab panel used inside Tabs.",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
}
]
}
このファイルが正しく機能するかどうかは、いくつかのルールで決まります:
filesは明示的なリストです。 CLI はこれらのパスだけをダウンロードし、それ以外はダウンロードしません。グロブ展開は行われないため、新しいアセットを含めるにはここに追加する必要があります。パスにはサブディレクトリを含めることができ、インストール時に作成されます。baseUrlは絶対 URL でなければなりません。 CLI は値を URL として検証し、相対値を拒否します。ブロックファイルは常にbaseUrlから取得され、registry.jsonが読み込まれた場所を基準に取得されることはありません。dependenciesは同じレジストリ内のブロックを指定します。tabsを追加すると、まずtab-itemがインストールされます。依存関係が不足している場合や循環している場合は、エラーが発生してインストールが中止されます。nameは必須ですが、表示されません。 コマンドと出力では、コンシューマーがblocks.jsonでレジストリに指定したキーを使用します。このキーは一致している必要はありません。typeは参考情報です。blockstudio、create-block、またはwordpressを受け入れますが、CLI の動作には影響しません。
CLIは取得のたびにファイル全体を検証し、問題のある各フィールドを報告します。そのため、ファイルのダウンロード前にタイプミスを見つけられます。$schemaの行を追加すると、エディターでも同じチェックができます。
手順4: raw URLで公開する
リポジトリをGitHubにコミットしてプッシュします。これで公開リポジトリ内のすべてのファイルに、次のURLからアクセスできます:
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
<ref>には、ブランチ、タグ、コミットSHAのいずれかを指定します。このレジストリでは、次の2つのURLが重要です:
- 利用側が設定するレジストリURL:
https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json registry.json内のbaseUrl:https://raw.githubusercontent.com/acme/acme-blocks/main/blocks
このbaseUrlを使うと、heroのindex.phpはhttps://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.phpから取得されます。
rawホストはCLIが必要とするファイルの内容を返し、HTMLのGitHubページは返しません。所有者、リポジトリ、参照先のいずれかが間違っている場合、最初のコマンドで404が表示されます:
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
手順5: テーマにブロックをインストールする
利用するテーマのルートにblocks.jsonを作成します:
npx blockstudio init --yes
Created .../acme-theme/blocks.json
init --yesは空のregistriesオブジェクトを書き込みます。コマンドで入力しやすい名前空間を指定して、その下にレジストリを追加します:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
代わりに、ターミナルで--yesを指定せずにinitを実行すると、同じ項目(ブロックディレクトリ、レジストリ名、URL)を対話形式で入力できます。
レジストリが解決できることを確認します:
npx blockstudio list
acme (4 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
tabs Tabs layout blockstudio
tab-item Tab Item layout blockstudio
searchは名前、タイトル、説明を対象に、大文字と小文字を区別しない部分一致で検索します:
npx blockstudio search tab
Results for "tab"
acme/tabs - Tabs
Tabbed content with keyboard navigation.
acme/tab-item - Tab Item
Single tab panel used inside Tabs.
--dry-runでインストールをプレビューします。依存関係は先にインストールされるため、一覧の先頭に表示されます:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
続いて実際にインストールします:
npx blockstudio add acme/tabs
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)
これで、リポジトリ内とまったく同じ構成で、両方のフォルダーがテーマのblockstudioディレクトリに配置されます:
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss
設定済みのレジストリが1つだけブロックを持つ場合は、名前空間を省略して、複数のブロックをまとめて渡せます:
npx blockstudio add hero card
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)
Blockstudioは、テーマ内のほかのブロックと同じように新しいフォルダーを認識します。
インストール済みブロックの更新
インストールされたファイルはコピーです。インストールしたバージョンを追跡する仕組みはなく、CLIがブロックを自動更新することもありません。新しいバージョンを取得するには、ブロックをもう一度追加します。ターミナルを使わない場合やCIでは、既存のフォルダーがあるとコマンドは停止します:
npx blockstudio add tab-item
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.
ターミナルでは、CLIは上書きするかどうかを確認します。--dry-runは置き換えるフォルダーを表示し、--yesはそれらを置き換えます:
npx blockstudio add acme/tab-item --dry-run
Would overwrite tab-item
Would install:
tab-item (2 files)
上書きすると、一覧にあるファイルがレジストリのバージョンに置き換わるため、先にローカルの変更をコミットし、git diffで結果を確認してください。
アンインストールするには、名前を指定してフォルダーを削除します:
npx blockstudio remove tabs --yes
Removed tabs
removeに指定するのはフォルダー名であり、namespace/blockではありません。依存関係は削除されないため、tabsを削除してもtab-itemはインストールされたままです。
git refによるバージョン管理
CLIにはバージョンフィールドもバージョンフラグもありません。取得する内容はURLだけで決まり、GitHubではURL内のrefがバージョンになります。mainを指定した利用者は、インストール時点でmainにある内容を取得します。
固定されたリリースを公開するには、タグのregistry.jsonもタグからダウンロードするようにします。タグを付ける前に、baseUrlをそのタグに設定します:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
次にコミットし、タグを付けて、プッシュします:
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0
その後、baseUrlをmainに戻してコミットし、ブランチが最新のファイルを提供できるようにします。最初の手順を省くと、タグに固定した利用者にはタグ付け時のブロック一覧が表示されますが、ファイルはmainからダウンロードされます。
利用者は、レジストリのURLでタグを指定してバージョンを固定します:
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
この例では、tabsとtab-itemが存在する前にv1.0.0にタグが付けられたため、固定されたレジストリには元の2つのブロックだけが表示されます:
npx blockstudio list
acme (2 blocks)
Name Title Category Type
hero Hero layout blockstudio
card Card components blockstudio
npx blockstudio add acme/tabs
Block "tabs" not found in registry "acme".
コミットSHAもレジストリのURLで使えますが、コミット自身のSHAをbaseUrlに含めることはできません。そのためSHAで固定するとブロック一覧は固定されますが、ファイルはそのコミットのbaseUrlが指すrefから取得されます。リリースにはタグを使うことをおすすめします。
知っておきたいこと
- すべてのレジストリを先に取得します。
addは何かを解決する前にblocks.json内のすべてのレジストリを読み込むため、acme/heroの場合でも、到達できないレジストリが1つあるとコマンドは失敗します。使わなくなったレジストリは削除してください。 - 名前が重複する場合は名前空間を指定します。 2つのレジストリに同じ
heroがある場合、ターミナルではどちらを使うか尋ねられ、--yesはblocks.jsonの順で最初のものを使い、非対話型の実行はBlock "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/heroで終了します。 - プライベートリポジトリにはヘッダーが必要です。
urlとheadersを指定したレジストリエントリーのオブジェクト形式を使ってください。ヘッダー値には環境変数から読み込む${VAR}プレースホルダーを使用できます。CLIはレジストリの取得時と各ファイルのダウンロード時にヘッダーを送信します。トークンの設定についてはGitHubホスティングを参照してください。
次のステップ
- レジストリの概要: レジストリの概要とCLIの仕組み
- registry.json: マニフェストのすべてのフィールド
- blocks.json: 利用者の設定、認証、設定の検出
- add: 名前空間の解決、依存関係、上書きの動作
- GitHubホスティング: GitHub Pagesとプライベートリポジトリ
- カスタムサーバー: 独自のインフラからレジストリを配信する