registry.json
registry.json は URL でホストされる JSON ファイルです。レジストリで利用可能なすべてのブロックと、そのメタデータ、依存関係、ファイルマニフェストを一覧にします。
スキーマ
{
"$schema": "https://blockstudio.dev/schema/registry.json",
"name": "ui",
"description": "Core UI blocks for Blockstudio projects.",
"baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
"blocks": [
{
"name": "tabs",
"title": "Tabs",
"description": "Tabbed content with accessible keyboard navigation.",
"category": "layout",
"type": "blockstudio",
"dependencies": ["tab-item"],
"files": [
"block.json",
"index.php",
"style.scss"
]
}
]
}
トップレベルのフィールド
name
必須。 レジストリ識別子です。CLI はこの値を検証しますが、表示はしません。コマンドと出力では、利用側が blocks.json でレジストリに指定したキーを使います。
description
省略可能。このレジストリに含まれる内容の簡単な説明です。
baseUrl
必須。 ブロックファイルのダウンロードに使うベース URL です。有効な URL である必要があります。
ファイルはベース URL、ブロック名、ファイルパスを組み合わせて取得されます: {baseUrl}/{block.name}/{file}
たとえば、baseUrl が https://raw.githubusercontent.com/acme/blocks/main/blocks で、tabs という名前のブロックに index.php というファイルがある場合、CLI は次を取得します:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
ブロックのフィールド
name
必須。 ブロックのフォルダー名です。CLI コマンドで使われる識別子であり、ディスク上のフォルダー名になります。
title
省略可能。list と search の出力に表示される、人が読みやすい名前です。
description
省略可能。search の結果に表示される1行の説明です。
category
省略可能。list の出力をグループ化するラベルです。
type
省略可能。blockstudio、create-block、wordpress のいずれかです。
これは情報提供のみを目的とします。CLI はブロックの種類に応じて動作を変えません。files に記載されたファイルを常にダウンロードしてコピーします。
dependencies
省略可能。同じレジストリ内で、このブロックと一緒にインストールする必要がある他のブロック名の配列です。
依存関係を持つブロックを追加すると、CLI は依存関係のツリー全体を解決し、正しい順序ですべてをインストールします。循環依存は検出され、拒否されます。
依存関係は同じレジストリ内に存在する必要があります。レジストリをまたぐ依存関係には対応していません。
files
必須。 ブロックフォルダーからの相対パスで示すファイルパスの配列です。少なくとも1つのファイルが必要です。
これらは CLI がダウンロードしてディスクに書き込むファイルそのものです。パスにはサブディレクトリを含められます:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
ファイルの解決
ブロックのマニフェスト内の各ファイルについて、CLI はダウンロード URL を組み立てます:
{baseUrl}/{block.name}/{file}
次の場所に書き込みます:
{directory}/{block.name}/{file}
ブロックフォルダー内のディレクトリ構造は維持されます。ファイルパスにサブディレクトリが含まれる場合は、自動的に作成されます。
ファイルは常に registry.json 内の baseUrl から取得されます。blocks.json のレジストリ URL からの相対パスで指定された場所から取得されることはありません。
検証
CLI は取得のたびに、registry.json を Zod スキーマに照らして検証します。レジストリが無効な場合は、検証に失敗した具体的なフィールドを含む、わかりやすいエラーメッセージが表示されます。
必須フィールドの欠落、空の blocks または files 配列、無効な URL、不明な type 値は、ファイルのダウンロード開始前にすべて検出されます。