Перейти до вмісту

registry.json

registry.json — це файл JSON, розміщений на URL. У ньому наведено всі доступні в реєстрі блоки, їхні метадані, залежності та маніфести файлів.

Схема

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

Поля верхнього рівня

name

Обов’язково. Ідентифікатор реєстру. CLI перевіряє його, але не відображає: у командах і результатах використовується ключ, який користувач вибрав для реєстру в blocks.json.

description

Необов’язково. Короткий опис вмісту реєстру.

baseUrl

Обов’язково. Базовий URL для завантаження файлів блоків. Має бути дійсним URL.

Файли отримуються шляхом об’єднання базового URL, назви блоку та шляху до файлу: {baseUrl}/{block.name}/{file}.

Наприклад, якщо baseUrl має значення https://raw.githubusercontent.com/acme/blocks/main/blocks, є блок tabs і файл index.php, CLI отримує:

Код
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php

Поля блоку

name

Обов’язково. Назва папки блоку. Цей ідентифікатор використовується в командах CLI і стає назвою папки на диску.

title

Необов’язково. Зрозуміла користувачам назва, що відображається в list та виведенні search.

description

Необов’язково. Короткий опис, що відображається в результатах search.

category

Необов’язково. Мітка групування для виведення list.

type

Необов’язково. Одне зі значень: blockstudio, create-block або wordpress.

Це поле має лише інформаційний характер. CLI не змінює поведінку залежно від типу блоку. Завжди завантажуються та копіюються файли, перелічені в files.

dependencies

Необов’язково. Масив назв інших блоків у тому самому реєстрі, які потрібно встановити разом із цим блоком.

Коли користувач додає блок із залежностями, CLI визначає повне дерево залежностей і встановлює все в правильному порядку. Циклічні залежності виявляються, і команда завершується помилкою.

Залежності мають бути в тому самому реєстрі. Залежності між реєстрами не підтримуються.

files

Обов’язково. Масив шляхів до файлів відносно папки блоку. Потрібен принаймні один файл.

Це точний перелік файлів, які CLI завантажує та записує на диск. Шляхи можуть містити вкладені каталоги:

JSON
{
  "files": [
    "block.json",
    "index.php",
    "style.scss",
    "src/components/tabs.tsx",
    "src/styles/tabs.css"
  ]
}

Визначення шляхів до файлів

Для кожного файлу в маніфесті блоку CLI формує URL для завантаження:

Код
{baseUrl}/{block.name}/{file}

І записує його в:

Код
{directory}/{block.name}/{file}

Структура каталогів усередині папки блоку зберігається. Якщо шлях до файлу містить вкладені каталоги, вони створюються автоматично.

Файли завжди отримуються з baseUrl усередині registry.json, а не з розташування відносно URL реєстру в blocks.json.

Перевірка даних

Під час кожного отримання registry.json CLI перевіряє за схемою Zod. Для некоректних реєстрів виводяться зрозумілі повідомлення про помилки із зазначенням полів, які не пройшли перевірку.

Відсутні обов’язкові поля, порожні масиви blocks або files, недійсні URL-адреси та невідомі значення type виявляються до завантаження файлів.