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
{
"$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):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Objektumformátum (hitelesítést igénylő regiszterek):
{
"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
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Alapszintű hitelesítés
{
"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:
{
"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:
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.
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
{
"$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
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}