Към съдържанието

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