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ă
{
"$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:
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:
{
"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:
{baseUrl}/{block.name}/{file}
Și îl scrie în:
{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.