Przejdź do treści

blocks.json

blocks.json znajduje się w katalogu głównym motywu lub wtyczki. Wskazuje CLI, gdzie instalować bloki i które rejestry przeszukiwać.

Schemat

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"
  }
}

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):

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

Format obiektu (rejestry wymagające uwierzytelnienia):

JSON
{
  "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

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

Uwierzytelnianie podstawowe

JSON
{
  "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:

JSON
{
  "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:

Powłoka
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.

Kod
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

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"
  }
}

Przykład: wtyczka z niestandardowym katalogiem

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