본문으로 건너뛰기

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