registry.json
registry.json je soubor JSON umístěný na serveru URL. Uvádí všechny bloky dostupné v registru, jejich metadata, závislosti a manifesty souborů.
Schéma
{
"$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"
]
}
]
}
Pole nejvyšší úrovně
name
Povinné. Identifikátor registru. CLI jej ověří, ale nezobrazuje: příkazy i výstup používají klíč, který uživatel zvolil pro registr v blocks.json.
description
Nepovinné. Stručný popis obsahu registru.
baseUrl
Povinné. Základní URL pro stahování souborů bloků. Musí jít o platnou hodnotu URL.
Soubory se načítají složením základního URL, názvu bloku a cesty k souboru: {baseUrl}/{block.name}/{file}.
Pokud je baseUrl nastaven na https://raw.githubusercontent.com/acme/blocks/main/blocks a blok tabs obsahuje soubor index.php, CLI stáhne:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Pole bloku
name
Povinné. Název složky bloku. Tento identifikátor se používá v příkazech CLI a stane se názvem složky na disku.
title
Nepovinné. Název pro uživatele zobrazovaný ve výstupech list a search.
description
Nepovinné. Jednořádkový popis zobrazovaný ve výsledcích search.
category
Nepovinný. Štítek pro seskupení ve výstupu list.
type
Nepovinné. Jedna z hodnot blockstudio, create-block nebo wordpress.
Slouží pouze jako informace. CLI nemění chování podle typu bloku. Vždy stáhne a zkopíruje soubory uvedené v files.
dependencies
Nepovinné. Pole názvů dalších bloků ve stejném registru, které je nutné nainstalovat spolu s tímto blokem.
Když uživatel přidá blok se závislostmi, CLI rozliší celý strom závislostí a vše nainstaluje ve správném pořadí. Kruhové závislosti zjistí a odmítne.
Závislosti musí být ve stejném registru. Závislosti napříč registry nejsou podporovány.
files
Povinné. Pole cest k souborům relativních vůči složce bloku. Je vyžadován alespoň jeden soubor.
Jde o přesné soubory, které CLI stáhne a zapíše na disk. Cesty mohou obsahovat podsložky:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Vyhledání souborů
Pro každý soubor uvedený v manifestu bloku sestaví CLI adresu pro stažení URL:
{baseUrl}/{block.name}/{file}
A zapíše jej do:
{directory}/{block.name}/{file}
Struktura adresářů uvnitř složky bloku se zachová. Pokud cesta k souboru obsahuje podsložky, vytvoří se automaticky.
Soubory se vždy načítají z baseUrl uvnitř registry.json, nikoli z umístění relativního k registru URL v blocks.json.
Validace
CLI při každém načtení ověřuje registry.json podle schématu Zod. Neplatné registry způsobí srozumitelnou chybovou zprávu, která uvede pole, jež neprošla ověřením.
Chybějící povinná pole, prázdná pole blocks nebo files, neplatné adresy URL a neznámé hodnoty type se zachytí ještě před stažením souborů.