Ugrás a tartalomhoz

blocks.json

A blocks.json a témád vagy bővítményed gyökérkönyvtárában található. Megadja a CLI számára, hogy hová telepítse a blokkokat, és mely regiszterekben keressen.

Séma

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

Mezők

$schema

Nem kötelező. A szerkesztő automatikus kiegészítéséhez és ellenőrzéséhez a JSON sémára mutat.

directory

Kötelező. A blocks.json-hoz képest megadott relatív elérési út, ahol a blokkok települnek.

Minden blokk saját almappát kap ebben a könyvtárban. Ha a directory értéke blockstudio, és hozzáadod ezt: hero, a fájlok ide kerülnek: blockstudio/hero/.

registries

Kötelező. A névterek nevét regiszterhivatkozásokhoz rendelő objektum.

A kulcs az CLI parancsokban használt névtér (npx blockstudio add ui/hero). Az érték lehet URL karakterlánc, vagy url és opcionálisan headers mezőt tartalmazó objektum.

Karakterlánc-formátum (nyilvános regiszterek):

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

Objektumformátum (hitelesítést igénylő regiszterek):

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

A két formátum vegyesen is használható ugyanabban a konfigurációban. Tetszőleges számú regisztert állíthatsz be. Ha névtér megadása nélkül adsz hozzá blokkot, a CLI mindegyikben keres.

Hitelesítés

A hitelesítést igénylő regiszterekhez a headers mezőt tartalmazó objektumformátumot használd. A CLI minden, az adott regiszterhez intézett kéréshez elküldi ezeket a fejléceket, beleértve a registry.json lekérését és az egyes fájlok letöltését is.

Bearer token

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

Alapszintű hitelesítés

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

Egyéni fejlécek

Bármilyen fejléc megadható. Ez használható például API kulcsokhoz, szervezetazonosítókhoz, illetve bármihez, amit a regiszterszerver megkövetel:

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

Környezeti változók

A fejlécértékek az ${VAR_NAME} szintaxissal olvashatnak be környezeti változókat. Így a tokenek nem kerülnek verziókezelésbe.

A CLI futásidőben oldja fel a környezeti változókat. Ha egy hivatkozott változó nincs beállítva, a CLI hibával kilép, és megnevezi a hiányzó változót, valamint azt a fejlécet, amelyben használták.

Állítsd be a változót a rendszerhéjban vagy a CI-környezetben. A CLI csak a folyamat környezetéből olvas; önállóan nem tölti be az .env fájlokat:

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

A statikus fejlécértékeket (az ${...} nélkül) változtatás nélkül továbbítja.

Konfiguráció felderítése

A CLI az aktuális munkakönyvtártól felfelé haladva keresi a blocks.json fájlt. Így a projekted bármely alkönyvtárából futtathatsz parancsokat.

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

Ha nem talál blocks.json fájlt, a CLI azt kéri, hogy futtasd ezt: npx blockstudio init.

Példa: téma két regiszterrel

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

Példa: bővítmény egyéni könyvtárral

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