Preskočiť na obsah

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

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

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:

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

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

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

A zapíše ho do:

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