registry.json
A registry.json egy JSON fájl, amelyet egy URL tárol. Felsorolja a regiszter összes elérhető blokkját, azok metaadatait, függőségeit és fájlmanifestjeit.
Séma
{
"$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"
]
}
]
}
Legfelső szintű mezők
name
Kötelező. A regiszter azonosítója. A CLI ellenőrzi ezt az értéket, de nem jeleníti meg: a parancsok és a kimenet a regiszterhez az blocks.json konfigurációban választott kulcsot használják.
description
Nem kötelező. Rövid leírás a regiszter tartalmáról.
baseUrl
Kötelező. A blokkfájlok letöltéséhez használt alap URL. Érvényes URL-nek kell lennie.
A fájlok lekérése az alap URL, a blokk neve és a fájl elérési útjának összefűzésével történik: {baseUrl}/{block.name}/{file}.
Ha például a baseUrl értéke
https://raw.githubusercontent.com/acme/blocks/main/blocks, a blokk neve pedig tabs, és tartalmazza a index.php fájlt, a CLI innen tölti le a fájlt:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Blokkmezők
name
Kötelező. A blokk mappaneve. Ezt az azonosítót használják az CLI parancsok, és ez lesz a lemezen létrehozott mappa neve is.
title
Nem kötelező. Emberi olvasásra alkalmas név, amely az list kimenetében és az search kimenetében jelenik meg.
description
Nem kötelező. Egysoros leírás, amely az search találatai között jelenik meg.
category
Nem kötelező. Csoportosítási címke az list kimenetéhez.
type
Nem kötelező. A blockstudio, create-block vagy wordpress egyike.
Ez a mező csak tájékoztató jellegű. A CLI a blokk típusa alapján nem módosítja a működését. Mindig letölti és másolja az files mezőben felsorolt fájlokat.
dependencies
Nem kötelező. Tömb, amely a ugyanabban a regiszterben található azon blokkok nevét tartalmazza, amelyeket ezzel a blokkal együtt kell telepíteni.
Ha egy felhasználó függőségekkel rendelkező blokkot ad hozzá, a CLI feloldja a teljes függőségi fát, majd mindent a megfelelő sorrendben telepít. A körkörös függőségeket felismeri és elutasítja.
A függőségeknek ugyanabban a regiszterben kell létezniük. A regiszterek közötti függőségek nem támogatottak.
files
Kötelező. A blokkmappához képest megadott relatív fájlelérési utak tömbje. Legalább egy fájlt meg kell adni.
Ezek azok a fájlok, amelyeket a CLI letölt és a lemezre ír. Az elérési utak alkönyvtárakat is tartalmazhatnak:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Fájlok feloldása
A blokk manifestjének minden fájljához a CLI létrehoz egy letöltési URL értéket:
{baseUrl}/{block.name}/{file}
A fájlt pedig ide írja:
{directory}/{block.name}/{file}
A blokkmappán belüli könyvtárstruktúra megmarad. Ha egy fájl elérési útja alkönyvtárakat tartalmaz, azok automatikusan létrejönnek.
A fájlokat a rendszer mindig a registry.json-ben lévő baseUrl helyről kéri le, nem az blocks.json fájlban megadott regiszter-URL-hoz képesti helyről.
Érvényesítés
A CLI minden lekéréskor ellenőrzi a registry.json érvényességét egy Zod séma alapján.
Érvénytelen regiszter esetén egyértelmű hibaüzenetet ad, amely megnevezi az ellenőrzésen megbukott mezőket.
A hiányzó kötelező mezőket, az üres blocks vagy files tömböket, az érvénytelen URL-eket és az ismeretlen type értékeket a rendszer még a fájlok letöltése előtt észleli.