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

blocks.json

blocks.json се намира в основната директория на темата или разширението ви. Файлът указва на CLI къде да инсталира блокове и в кои регистри да търси.

Схема

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}

Полета

$schema

По избор. Указва схемата JSON за автоматично довършване и проверка в редактора.

directory

Задължително. Относителен път от blocks.json, където се инсталират блоковете.

Всеки блок получава собствена подпапка в тази директория. Ако directory е blockstudio и добавите hero, файловете ще бъдат записани в blockstudio/hero/.

registries

Задължително. Обект, който съпоставя имената на пространствата от имена с препратки към регистри.

Ключът е пространството от имена, използвано в командите CLI (npx blockstudio add ui/hero). Стойността е или низ във формат URL, или обект с url и незадължително headers.

Формат с низ (публични регистри):

JSON
{
  "registries": {
    "ui": "https://example.com/registry.json"
  }
}

Обектен формат (регистри с удостоверяване):

JSON
{
  "registries": {
    "private": {
      "url": "https://private.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Можете да комбинирате двата формата в една конфигурация и да зададете произволен брой регистри. Когато добавя блок без пространство от имена, CLI търси във всички тях.

Удостоверяване

За регистрите, които изискват удостоверяване, използвайте обектния формат с headers. CLI изпраща тези заглавки при всяка заявка към регистъра, включително при извличането на registry.json и изтеглянето на отделни файлове.

Bearer токен

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Basic удостоверяване

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Basic ${REGISTRY_CREDENTIALS}"
      }
    }
  }
}

Персонализирани заглавки

Може да се добави всяка заглавка. Това работи за ключове API, идентификатори на организации и всякакви други стойности, които сървърът на регистъра изисква:

JSON
{
  "registries": {
    "internal": {
      "url": "https://blocks.internal.company.com/registry.json",
      "headers": {
        "X-API-Key": "${BLOCKS_API_KEY}",
        "X-Org-ID": "acme"
      }
    }
  }
}

Променливи на средата

Стойностите на заглавките поддържат синтаксиса ${VAR_NAME} за четене на променливи на средата. Така токените не попадат в системата за контрол на версиите.

CLI разрешава променливите на средата по време на изпълнение. Ако посочена променлива не е зададена, CLI прекратява командата с грешка, в която са посочени липсващата променлива и заглавката, в която е използвана.

Задайте променливата в обвивката или средата за CI. CLI чете само средата на процеса; самостоятелно не зарежда файлове .env:

Обвивка
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Статичните стойности на заглавките (без ${...}) се предават без промяна.

Откриване на конфигурацията

CLI се изкачва от текущата работна директория, докато намери blocks.json. Така можете да изпълнявате команди от всяка поддиректория на проекта си.

Код
my-theme/
  blocks.json        <- found here
  blockstudio/
    hero/
  templates/
    page.php          <- running `npx blockstudio add` here still works

Ако не бъде намерен blocks.json, CLI ви казва да изпълните npx blockstudio init.

Пример: тема с два регистъра

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.mycompany.com/ui/registry.json",
    "internal": "https://blocks.mycompany.com/internal/registry.json"
  }
}

Пример: разширение с персонализирана директория

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "src/blocks",
  "registries": {
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}