Přejít k obsahu

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

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"
      ]
    }
  ]
}

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:

Kód
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:

JSON
{
  "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:

Kód
{baseUrl}/{block.name}/{file}

A zapíše jej do:

Kód
{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ů.