Treci la conținut

registry.json

registry.json este un fișier JSON găzduit pe un server URL. Enumeră toate blocurile disponibile într-un registru, metadatele acestora, dependențele și manifestele fișierelor.

Schemă

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

Câmpuri de nivel superior

name

Obligatoriu. Identificatorul registrului. CLI îl validează, dar nu îl afișează: comenzile și rezultatele folosesc cheia aleasă de utilizatorul registrului în blocks.json.

description

Opțional. O descriere scurtă a conținutului acestui registru.

baseUrl

Obligatoriu. URL de bază pentru descărcarea fișierelor blocurilor. Trebuie să fie o URL validă.

Fișierele sunt preluate prin combinarea valorii URL de bază, a numelui blocului și a căii fișierului: {baseUrl}/{block.name}/{file}.

De exemplu, dacă baseUrl este https://raw.githubusercontent.com/acme/blocks/main/blocks, iar un bloc numit tabs are fișierul index.php, CLI preia:

Cod
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php

Câmpuri ale blocului

name

Obligatoriu. Numele directorului blocului. Acesta este identificatorul folosit în comenzile CLI și devine numele directorului de pe disc.

title

Opțional. Nume ușor de înțeles, afișat în rezultatele list și search.

description

Opțional. Descriere pe un singur rând, afișată în rezultatele search.

category

Opțional. Etichetă de grupare pentru rezultatele list.

type

Opțional. Una dintre valorile blockstudio, create-block sau wordpress.

Are doar rol informativ. CLI nu își schimbă comportamentul în funcție de tipul blocului. Descarcă și copiază întotdeauna fișierele enumerate în files.

dependencies

Opțional. O listă cu numele altor blocuri din același registru care trebuie instalate împreună cu acest bloc.

Când un utilizator adaugă un bloc cu dependențe, CLI rezolvă întregul arbore de dependențe și instalează totul în ordinea corectă. Dependențele circulare sunt detectate și respinse.

Dependențele trebuie să existe în același registru. Dependențele între registre nu sunt acceptate.

files

Obligatoriu. O listă de căi către fișiere, relative la directorul blocului. Este necesar cel puțin un fișier.

Acestea sunt fișierele exacte pe care CLI le descarcă și le scrie pe disc. Căile pot include subdirectoare:

JSON
{
  "files": [
    "block.json",
    "index.php",
    "style.scss",
    "src/components/tabs.tsx",
    "src/styles/tabs.css"
  ]
}

Rezolvarea căilor fișierelor

Pentru fiecare fișier din manifestul unui bloc, CLI construiește o adresă de descărcare URL:

Cod
{baseUrl}/{block.name}/{file}

Și îl scrie în:

Cod
{directory}/{block.name}/{file}

Structura directoarelor din directorul blocului este păstrată. Dacă o cale de fișier conține subdirectoare, acestea sunt create automat.

Fișierele sunt preluate întotdeauna din baseUrl din registry.json, nu dintr-o locație relativă la registrul URL din blocks.json.

Validare

CLI validează registry.json conform unei scheme Zod la fiecare preluare. Registrele invalide generează mesaje de eroare clare, care indică exact câmpurile cu probleme.

Câmpurile obligatorii lipsă, listele blocks sau files goale, URL-urile invalide și valorile type necunoscute sunt detectate înainte de descărcarea fișierelor.