blocks.json
blocks.json은 테마 또는 플러그인의 루트에 있습니다. 블록을 설치할 위치와 검색할 레지스트리를 CLI에 지정합니다.
스키마
{
"$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가 포함된 객체입니다.
문자열 형식(공개 레지스트리):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
객체 형식(인증이 필요한 레지스트리):
{
"registries": {
"private": {
"url": "https://private.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
두 형식을 같은 구성에서 함께 사용할 수 있습니다. 원하는 만큼 레지스트리를 구성할 수 있습니다. 네임스페이스 없이 블록을 추가하면 CLI이 모든 레지스트리에서 검색합니다.
인증
인증이 필요한 레지스트리에는 headers이 포함된 객체 형식을 사용합니다.
CLI은 registry.json 가져오기와 개별 파일 다운로드를 포함해 해당 레지스트리에 보내는 모든 요청에 이 헤더를 전송합니다.
Bearer 토큰
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Basic 인증
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Basic ${REGISTRY_CREDENTIALS}"
}
}
}
}
사용자 지정 헤더
API 키, 조직 식별자 등 레지스트리 서버가 요구하는 모든 헤더를 추가할 수 있습니다:
{
"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을 실행하라고 안내합니다.
예시: 레지스트리 두 개를 사용하는 테마
{
"$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"
}
}
예시: 사용자 지정 디렉터리를 사용하는 플러그인
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}