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 се откриват преди изтеглянето на файлове.