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.
Перевірка даних
Під час кожного отримання registry.json CLI перевіряє за схемою Zod. Для некоректних реєстрів виводяться зрозумілі повідомлення про помилки із зазначенням полів, які не пройшли перевірку.
Відсутні обов’язкові поля, порожні масиви blocks або files, недійсні URL-адреси та невідомі значення type виявляються до завантаження файлів.