blocks.json
blocks.json はテーマまたはプラグインのルートに置きます。ブロックのインストール先と検索対象のレジストリを CLI に指定します。
スキーマ
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"ui": "https://blocks.example.com/registry.json",
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}
フィールド
$schema
省略可能。エディターの自動補完と検証に使用する JSON スキーマへの参照です。
directory
必須。 ブロックのインストール先を示す、blocks.json からの相対パスです。
このディレクトリ内には、ブロックごとにサブフォルダーが作成されます。directory が blockstudio で、hero を追加すると、ファイルは blockstudio/hero/ に配置されます。
registries
必須。 名前空間名とレジストリ参照を対応付けるオブジェクトです。
キーは CLI コマンドで使う名前空間 (npx blockstudio add ui/hero) です。値には URL 文字列、または url と省略可能な headers を含むオブジェクトを指定します。
文字列形式 (公開レジストリ):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
オブジェクト形式 (認証が必要なレジストリ):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
どちらの形式も同じ設定内で混在させられます。レジストリはいくつでも設定できます。名前空間を指定せずにブロックを追加すると、CLI はすべてのレジストリを検索します。
認証
認証が必要なレジストリには、headers を使ったオブジェクト形式を指定します。CLI は、そのレジストリへのすべてのリクエストでこれらのヘッダーを送信します。registry.json の取得と個別ファイルのダウンロードの両方が対象です。
ベアラートークン
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Basic 認証
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
カスタムヘッダー
任意のヘッダーを追加できます。API キー、組織識別子など、レジストリサーバーが要求する値を指定できます:
{
"registries": {
"internal": {
"url": "https://blocks.internal.company.com/registry.json",
"headers": {
"X-API-Key": "${BLOCKS_API_KEY}",
"X-Org-ID": "acme"
}
}
}
}
環境変数
ヘッダー値では ${VAR_NAME} 構文を使って環境変数を読み込めます。これにより、トークンをバージョン管理に含めずに済みます。
CLI は実行時に環境変数を解決します。参照先の変数が設定されていない場合、CLI は不足している変数名と、その変数が使われているヘッダーを示すエラーで終了します。
シェルまたは CI 環境で変数を設定してください。CLI はプロセス環境のみを読み取り、.env ファイルを自動で読み込むことはありません:
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero
${...} を含まない静的なヘッダー値は、そのまま渡されます。
設定ファイルの検索
CLI は現在の作業ディレクトリから上の階層へたどり、blocks.json を探します。そのため、プロジェクト内のどのサブディレクトリからでもコマンドを実行できます。
my-theme/
blocks.json <- found here
blockstudio/
hero/
templates/
page.php <- running `npx blockstudio add` here still works
blocks.json が見つからない場合、CLI は npx blockstudio init を実行するよう案内します。
例: 2つのレジストリを持つテーマ
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "blockstudio",
"registries": {
"ui": "https://blocks.mycompany.com/ui/registry.json",
"internal": "https://blocks.mycompany.com/internal/registry.json"
}
}
例: カスタムディレクトリを使うプラグイン
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}