registry.json
registry.json to plik JSON hostowany na URL. Zawiera listę wszystkich bloków dostępnych w rejestrze, ich metadane, zależności i manifesty plików.
Schemat
{
"$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"
]
}
]
}
Pola najwyższego poziomu
name
Wymagane. Identyfikator rejestru. CLI go weryfikuje, ale nie wyświetla: polecenia i dane wyjściowe używają klucza wybranego przez użytkownika dla rejestru w blocks.json.
description
Opcjonalnie. Krótki opis zawartości rejestru.
baseUrl
Wymagane. Podstawowy adres URL do pobierania plików bloków. Musi być prawidłowym URL.
Pliki są pobierane przez połączenie podstawowego adresu URL, nazwy bloku i ścieżki pliku: {baseUrl}/{block.name}/{file}.
Na przykład, jeśli baseUrl ma wartość
https://raw.githubusercontent.com/acme/blocks/main/blocks, a blok o nazwie
tabs zawiera plik index.php, CLI pobiera:
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php
Pola bloku
name
Wymagane. Nazwa folderu bloku. Ten identyfikator jest używany w poleceniach CLI i staje się nazwą folderu na dysku.
title
Opcjonalnie. Czytelna dla człowieka nazwa wyświetlana w list i danych wyjściowych search.
description
Opcjonalnie. Jednowierszowy opis wyświetlany w wynikach search.
category
Opcjonalnie. Etykieta grupująca w danych wyjściowych list.
type
Opcjonalnie. Jedna z wartości: blockstudio, create-block lub wordpress.
Ma wyłącznie charakter informacyjny. CLI nie zmienia działania w zależności od typu bloku. Zawsze pobiera i kopiuje pliki wymienione w files.
dependencies
Opcjonalnie. Tablica nazw innych bloków w tym samym rejestrze, które trzeba zainstalować razem z tym blokiem.
Gdy użytkownik dodaje blok z zależnościami, CLI rozpoznaje pełne drzewo zależności i instaluje wszystko we właściwej kolejności. Zależności cykliczne są wykrywane i odrzucane.
Zależności muszą istnieć w tym samym rejestrze. Zależności między rejestrami nie są obsługiwane.
files
Wymagane. Tablica ścieżek plików względem folderu bloku. Wymagany jest co najmniej jeden plik.
Są to dokładnie te pliki, które CLI pobiera i zapisuje na dysku. Ścieżki mogą zawierać podkatalogi:
{
"files": [
"block.json",
"index.php",
"style.scss",
"src/components/tabs.tsx",
"src/styles/tabs.css"
]
}
Rozpoznawanie ścieżek plików
Dla każdego pliku w manifeście bloku CLI tworzy adres pobierania URL:
{baseUrl}/{block.name}/{file}
Zapisuje go w:
{directory}/{block.name}/{file}
Struktura katalogów wewnątrz folderu bloku zostaje zachowana. Jeśli ścieżka pliku zawiera podkatalogi, są one tworzone automatycznie.
Pliki są zawsze pobierane z baseUrl w registry.json, a nie z lokalizacji względem rejestru URL w blocks.json.
Walidacja
Przy każdym pobieraniu CLI weryfikuje registry.json względem schematu Zod. Nieprawidłowe rejestry powodują wyświetlenie jasnych komunikatów o błędach wraz ze wskazaniem pól, które nie przeszły walidacji.
Brakujące wymagane pola, puste tablice blocks lub files, nieprawidłowe adresy URL i nieznane wartości type są wykrywane przed pobraniem jakichkolwiek plików.