registry.json
registry.json je súbor JSON hostovaný na URL. Uvádza všetky dostupné bloky v registri, ich metadáta, závislosti a manifesty súborov.
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"
]
}
]
}
Polia najvyššej úrovne
name
Povinné. Identifikátor registra. CLI ho overuje, ale nezobrazuje: príkazy a výstup používajú kľúč, ktorý používateľ zvolil pre register v blocks.json.
description
Voliteľné. Stručný popis obsahu registra.
baseUrl
Povinné. Základná URL na sťahovanie súborov blokov. Musí ísť o platnú URL.
Súbory sa načítavajú kombináciou základnej URL, názvu bloku a cesty k súboru: {baseUrl}/{block.name}/{file}.
Napríklad, ak je baseUrl nastavené na
https://raw.githubusercontent.com/acme/blocks/main/blocks a blok s názvom
tabs obsahuje súbor index.php, CLI ho načíta z tejto cesty:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Polia bloku
name
Povinné. Názov priečinka bloku. Tento identifikátor sa používa v príkazoch CLI a stane sa názvom priečinka na disku.
title
Voliteľné. Ľudsky čitateľný názov zobrazený vo výstupe list a search.
description
Voliteľné. Jednoriadkový popis zobrazený vo výsledkoch search.
category
Voliteľné. Označenie skupiny vo výstupe list.
type
Voliteľné. Jedna z hodnôt blockstudio, create-block alebo wordpress.
Slúži len na informačné účely. CLI nemení správanie podľa typu bloku. Vždy stiahne a skopíruje súbory uvedené v files.
dependencies
Voliteľné. Pole názvov ďalších blokov z toho istého registra, ktoré sa musia nainštalovať spolu s týmto blokom.
Keď používateľ pridá blok so závislosťami, CLI rozpozná celý strom závislostí a všetko nainštaluje v správnom poradí. Kruhové závislosti sa zistia a odmietnu.
Závislosti musia existovať v tom istom registri. Závislosti medzi registrami nie sú podporované.
files
Povinné. Pole ciest k súborom relatívnych k priečinku bloku. Vyžaduje sa aspoň jeden súbor.
Ide o presné súbory, ktoré CLI stiahne a zapíše na disk. Cesty môžu obsahovať podpriečinky:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Rozpoznávanie súborov
Pre každý súbor v manifeste bloku CLI vytvorí adresu URL na stiahnutie URL:
{baseUrl}/{block.name}/{file}
A zapíše ho do:
{directory}/{block.name}/{file}
Štruktúra adresárov v priečinku bloku zostane zachovaná. Ak cesta k súboru obsahuje podadresáre, vytvoria sa automaticky.
Súbory sa vždy načítavajú z baseUrl v rámci registry.json, nie z umiestnenia relatívneho k registru URL v blocks.json.
Validácia
Pri každom načítaní CLI overuje registry.json podľa schémy Zod.
Neplatné registre vyvolajú zrozumiteľné chybové hlásenia s uvedením polí, ktoré neprešli overením.
Chýbajúce povinné polia, prázdne polia blocks alebo files, neplatné adresy URL a neznáme hodnoty type sa zachytia ešte pred stiahnutím súborov.