Vai al contenuto

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

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

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:

Codice
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:

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

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

E lo salva in:

Codice
{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.