registry.json
registry.json — это файл JSON, размещенный на сервере URL. В нем перечислены все доступные в реестре блоки, их метаданные, зависимости и манифесты файлов.
Схема
{
"$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 загружает и записывает на диск. Пути могут включать вложенные каталоги:
{
"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.