Vai al contenuto

Guida introduttiva

Prerequisiti

  • Node.js 18+
  • Un tema o plugin WordPress in cui installare i blocchi

Il pacchetto blockstudio su npm è alla versione 0.0.1. Questa release è un segnaposto: include solo un comando add, che stampa Adding block: <name> e termina senza recuperare nulla; inoltre rifiuta init, list, search, remove, --yes e --dry-run perché sconosciuti. I comandi descritti in queste pagine corrispondono al registro CLI nel repository Blockstudio (packages/registry).

Inizializzare il progetto

Esegui init nella directory principale del tema o del plugin:

Shell
npx blockstudio init

CLI ti guida nella configurazione interattiva:

  1. Directory dei blocchi: dove installare i blocchi (predefinita: blockstudio)
  2. Registri: aggiungi uno o più URL di registro assegnando un nome

Viene creato un file blocks.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json"
  }
}

Puoi anche ignorare le richieste interattive:

Shell
npx blockstudio init --yes

Crea un file blocks.json con i valori predefiniti. In seguito puoi modificarlo manualmente.

Aggiungere un blocco

Shell
npx blockstudio add ui/tabs

Il formato è namespace/block, dove namespace corrisponde a una chiave nella configurazione registries.

CLI:

  1. Recupera il registro
  2. Trova il blocco
  3. Risolve eventuali dipendenze (e.g. tabs dipende da tab-item)
  4. Scarica tutti i file
  5. Li salva nella directory del tuo blocco

Se il blocco si trova in un solo registro, puoi omettere il namespace:

Shell
npx blockstudio add tabs

Se si trova in più registri, CLI ti chiede di scegliere in un terminale. Senza terminale, si interrompe con un errore che elenca i registri corrispondenti; --yes sceglie il primo in ordine blocks.json.

Aggiungere più blocchi

Shell
npx blockstudio add ui/tabs ui/hero ui/accordion

Tutti i blocchi vengono installati in un’unica esecuzione.

Anteprima prima dell’installazione

Shell
npx blockstudio add ui/tabs --dry-run

Mostra cosa verrebbe installato senza scrivere alcun file.

Esplorare i blocchi disponibili

Shell
npx blockstudio list
npx blockstudio list ui
npx blockstudio search hero

list mostra tutti i blocchi di tutti i registri, oppure di uno specifico. search cerca nei nomi, nei titoli e nelle descrizioni dei blocchi una sottostringa, senza distinguere tra maiuscole e minuscole.

Rimuovere un blocco

Shell
npx blockstudio remove tabs

Elimina la cartella del blocco. In modalità interattiva ti viene chiesto di confermare. Passa --yes per ignorare la richiesta.

CI e automazione

init, add e remove accettano --yes per ignorare i prompt interattivi. list e search non mostrano mai prompt e rifiutano --yes come opzione sconosciuta. Quando stdin non è un terminale (runner CI, input reindirizzato tramite pipe), CLI passa alla modalità non interattiva: init sovrascrive un blocks.json esistente, add si interrompe con un errore se una cartella del blocco esiste già o il nome del blocco è ambiguo, e remove elimina senza chiedere.

Shell
npx blockstudio init --yes --directory blockstudio
npx blockstudio add ui/tabs --yes
npx blockstudio remove tabs --yes