Перейти к содержимому

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.

Проверка данных

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

До загрузки файлов обнаруживаются отсутствующие обязательные поля, пустые значения blocks или массивы files, недействительные URL и неизвестные значения type.