registry.json
registry.json è un file JSON ospitato su un server URL. Elenca tutti i blocchi disponibili in un registro, i relativi metadati, le dipendenze e i manifest dei file.
Schema
{
"$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"
]
}
]
}
Campi di primo livello
name
Obbligatorio. Identificatore del registro. CLI lo convalida ma non lo mostra: comandi e output usano la chiave scelta dal consumer per il registro in blocks.json.
description
Facoltativo. Breve descrizione del contenuto del registro.
baseUrl
Obbligatorio. URL di base per scaricare i file dei blocchi. Deve essere un URL valido.
I file vengono recuperati combinando l’URL di base, il nome del blocco e il percorso del file: {baseUrl}/{block.name}/{file}.
Ad esempio, con baseUrl impostato su https://raw.githubusercontent.com/acme/blocks/main/blocks e un blocco chiamato tabs con il file index.php, CLI recupera:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Campi del blocco
name
Obbligatorio. Nome della cartella del blocco. È l’identificatore usato nei comandi CLI e diventa il nome della cartella sul disco.
title
Facoltativo. Nome leggibile mostrato nell’output di list e search.
description
Facoltativo. Descrizione di una riga mostrata nei risultati di search.
category
Facoltativo. Etichetta di raggruppamento per l’output di list.
type
Facoltativo. Uno tra blockstudio, create-block o wordpress.
È solo a scopo informativo. CLI non modifica il comportamento in base al tipo di blocco. Scarica e copia sempre i file elencati in files.
dependencies
Facoltativo. Array di altri nomi di blocchi dello stesso registro da installare insieme a questo blocco.
Quando un utente aggiunge un blocco con dipendenze, CLI risolve l’intero albero delle dipendenze e installa tutto nell’ordine corretto. Le dipendenze circolari vengono rilevate e rifiutate.
Le dipendenze devono trovarsi nello stesso registro. Le dipendenze tra registri diversi non sono supportate.
files
Obbligatorio. Array di percorsi dei file relativi alla cartella del blocco. È richiesto almeno un file.
Sono i file esatti che CLI scarica e salva su disco. I percorsi possono includere sottodirectory:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Risoluzione dei file
Per ogni file nel manifest di un blocco, CLI compone un URL di download:
{baseUrl}/{block.name}/{file}
E lo salva in:
{directory}/{block.name}/{file}
La struttura delle directory all’interno della cartella del blocco viene mantenuta. Se un percorso contiene sottodirectory, queste vengono create automaticamente.
I file vengono sempre recuperati da baseUrl all’interno di registry.json, non da una posizione relativa al URL del registro in blocks.json.
Convalida
A ogni recupero, CLI convalida registry.json rispetto a uno schema Zod. Per i registri non validi vengono mostrati messaggi di errore chiari con i campi specifici che non hanno superato la convalida.
I campi obbligatori mancanti, gli array blocks o files vuoti, gli URL non validi e i valori type sconosciuti vengono rilevati prima di scaricare qualsiasi file.