Treci la conținut

blocks.json

blocks.json se află în directorul rădăcină al temei sau modulului dvs. Indică CLI unde să instaleze blocurile și în ce registre să caute.

Schemă

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

Câmpuri

$schema

Opțional. Indică schema JSON pentru completarea automată și validarea în editor.

directory

Obligatoriu. Calea relativă de la blocks.json unde sunt instalate blocurile.

Fiecare bloc primește propriul subdirector în acest director. Dacă directory este blockstudio și adăugați hero, fișierele ajung în blockstudio/hero/.

registries

Obligatoriu. Un obiect care asociază nume de spații de nume cu referințe la registre.

Cheia este spațiul de nume folosit în comenzile CLI (npx blockstudio add ui/hero). Valoarea este fie un șir URL, fie un obiect cu url și headers opțional.

Format șir (registre publice):

JSON
{
  "registries": {
    "ui": "https://example.com/registry.json"
  }
}

Format obiect (registre autentificate):

JSON
{
  "registries": {
    "private": {
      "url": "https://private.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Puteți combina ambele formate în aceeași configurație. Puteți configura oricâte registre doriți. Când adăugați un bloc fără spațiu de nume, CLI le caută pe toate.

Autentificare

Registrele care necesită autentificare folosesc formatul obiect cu headers. CLI trimite aceste antete la fiecare solicitare către registrul respectiv, inclusiv pentru preluarea lui registry.json și pentru descărcările fișierelor individuale.

Token bearer

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Autentificare de bază

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Basic ${REGISTRY_CREDENTIALS}"
      }
    }
  }
}

Antete personalizate

Puteți adăuga orice antet. Funcționează pentru chei API, identificatori de organizații sau orice altceva așteaptă serverul registrului dvs.:

JSON
{
  "registries": {
    "internal": {
      "url": "https://blocks.internal.company.com/registry.json",
      "headers": {
        "X-API-Key": "${BLOCKS_API_KEY}",
        "X-Org-ID": "acme"
      }
    }
  }
}

Variabile de mediu

Valorile antetelor acceptă sintaxa ${VAR_NAME} pentru citirea variabilelor de mediu. Astfel, tokenurile nu sunt incluse în controlul versiunilor.

CLI rezolvă variabilele de mediu în timpul execuției. Dacă o variabilă referită nu este definită, CLI se încheie cu o eroare care indică numele variabilei lipsă și antetul în care a fost utilizată.

Definiți variabila în shell sau în mediul CI. CLI citește doar mediul procesului; nu încarcă de la sine fișierele .env:

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Valorile statice ale antetelor (fără ${...}) sunt transmise neschimbate.

Descoperirea configurației

CLI urcă din directorul de lucru curent, căutând blocks.json. Astfel, puteți rula comenzile din orice subdirector al proiectului.

Cod
my-theme/
  blocks.json        <- found here
  blockstudio/
    hero/
  templates/
    page.php          <- running `npx blockstudio add` here still works

Dacă nu este găsit niciun blocks.json, CLI vă spune să rulați npx blockstudio init.

Exemplu: temă cu două registre

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

Exemplu: modul cu director personalizat

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "src/blocks",
  "registries": {
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}