Przejdź do treści

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

JSON
{
  "$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:

Kod
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:

JSON
{
  "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:

Kod
{baseUrl}/{block.name}/{file}

Zapisuje go w:

Kod
{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.