コンテンツへスキップ

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つあります:

JSON
{
  "$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"
      }
    ]
  }
}
PHP
<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がダウンロードするすべてのファイルを記載します:

JSON
{
  "$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オブジェクトを書き込みます。コマンドで入力しやすい名前空間を指定して、その下にレジストリを追加します:

JSON
{
  "$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をそのタグに設定します:

JSON
"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でタグを指定してバージョンを固定します:

JSON
{
  "$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ホスティングを参照してください。

次のステップ