blocks.json
blocks.json znajduje się w katalogu głównym motywu lub wtyczki. Wskazuje CLI, gdzie instalować bloki i które rejestry przeszukiwać.
Schemat
{
"$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"
}
}
Pola
$schema
Opcjonalnie. Wskazuje schemat JSON, który umożliwia podpowiadanie i walidację w edytorze.
directory
Wymagane. Ścieżka względna od blocks.json, w której instalowane są bloki.
Każdy blok ma własny podfolder w tym katalogu. Jeśli directory to blockstudio, a dodasz hero, pliki znajdą się w blockstudio/hero/.
registries
Wymagane. Obiekt mapujący nazwy przestrzeni nazw na odwołania do rejestrów.
Klucz to przestrzeń nazw używana w poleceniach CLI (npx blockstudio add ui/hero).
Wartością jest ciąg znaków URL albo obiekt zawierający url oraz opcjonalnie headers.
Format ciągu znaków (rejestry publiczne):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Format obiektu (rejestry wymagające uwierzytelnienia):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Oba formaty można łączyć w tej samej konfiguracji. Można skonfigurować dowolną liczbę rejestrów. Przy dodawaniu bloku bez przestrzeni nazw CLI przeszukuje je wszystkie.
Uwierzytelnianie
Rejestry wymagające uwierzytelnienia używają formatu obiektu z headers.
CLI wysyła te nagłówki przy każdym żądaniu do danego rejestru, zarówno podczas pobierania registry.json, jak i poszczególnych plików.
Token Bearer
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Uwierzytelnianie podstawowe
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
Nagłówki niestandardowe
Można dodać dowolny nagłówek. Sprawdza się to w przypadku kluczy API, identyfikatorów organizacji i innych danych wymaganych przez serwer rejestru:
{
"registries": {
"internal": {
"url": "https://blocks.internal.company.com/registry.json",
"headers": {
"X-API-Key": "${BLOCKS_API_KEY}",
"X-Org-ID": "acme"
}
}
}
}
Zmienne środowiskowe
Wartości nagłówków obsługują składnię ${VAR_NAME} umożliwiającą odczyt zmiennych środowiskowych. Dzięki temu tokeny nie trafiają do kontroli wersji.
CLI odczytuje zmienne środowiskowe w czasie działania. Jeśli używana zmienna nie jest ustawiona, CLI kończy się błędem, podając nazwę brakującej zmiennej i nagłówek, w którym została użyta.
Ustaw zmienną w powłoce lub środowisku CI. CLI odczytuje wyłącznie zmienne środowiskowe procesu; samodzielnie nie wczytuje plików .env:
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero
Statyczne wartości nagłówków (bez ${...}) są przekazywane bez zmian.
Wyszukiwanie konfiguracji
CLI przechodzi w górę od bieżącego katalogu roboczego w poszukiwaniu blocks.json. Dzięki temu można uruchamiać polecenia z dowolnego podkatalogu projektu.
my-theme/
blocks.json <- found here
blockstudio/
hero/
templates/
page.php <- running `npx blockstudio add` here still works
Jeśli nie znaleziono blocks.json, CLI informuje o konieczności uruchomienia npx blockstudio init.
Przykład: motyw z dwoma rejestrami
{
"$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"
}
}
Przykład: wtyczka z niestandardowym katalogiem
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}