본문으로 건너뛰기

registry.json

registry.json은 URL에서 호스팅되는 JSON 파일입니다. 레지스트리에서 사용할 수 있는 모든 블록과 해당 메타데이터, 종속성 및 파일 매니페스트를 나열합니다.

스키마

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "ui",
  "description": "Core UI blocks for Blockstudio projects.",
  "baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
  "blocks": [
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with accessible keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": [
        "block.json",
        "index.php",
        "style.scss"
      ]
    }
  ]
}

최상위 필드

name

필수. 레지스트리 식별자입니다. CLI은 이를 검증하지만 표시하지 않습니다. 명령과 출력에는 blocks.json에서 레지스트리에 대해 사용자가 선택한 키가 사용됩니다.

description

선택 사항입니다. 이 레지스트리에 포함된 항목을 간단히 설명합니다.

baseUrl

필수. 블록 파일 다운로드를 위한 기본 URL입니다. 유효한 URL이어야 합니다.

기본 URL, 블록 이름 및 파일 경로를 결합해 파일을 가져옵니다: {baseUrl}/{block.name}/{file}.

baseUrl을 https://raw.githubusercontent.com/acme/blocks/main/blocks로 설정하고, 블록 이름이 tabs이며 파일이 index.php인 경우 CLI은 다음을 가져옵니다:

코드
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php

블록 필드

name

필수. 블록 폴더 이름입니다. CLI 명령에서 사용되는 식별자이며 디스크에 폴더 이름으로 생성됩니다.

title

선택 사항입니다. list 및 search 출력에 표시되는 사람이 읽을 수 있는 이름입니다.

description

선택 사항입니다. search 결과에 표시되는 한 줄 설명입니다.

category

선택 사항입니다. list 출력의 그룹화 레이블입니다.

type

선택 사항이며 blockstudio, create-block 또는 wordpress 중 하나입니다.

정보 제공용입니다. CLI은 블록 유형에 따라 동작을 변경하지 않습니다. files에 나열된 파일을 항상 다운로드하고 복사합니다.

dependencies

선택 사항입니다. 이 블록과 함께 설치해야 하는 같은 레지스트리 내 다른 블록 이름의 배열입니다.

사용자가 종속성이 있는 블록을 추가하면 CLI은 전체 종속성 트리를 확인하고 올바른 순서로 모두 설치합니다. 순환 종속성은 감지되어 거부됩니다.

종속성은 같은 레지스트리에 있어야 합니다. 레지스트리 간 종속성은 지원되지 않습니다.

files

필수. 블록 폴더 기준 상대 경로인 파일 경로의 배열입니다. 파일이 하나 이상 있어야 합니다.

CLI이 다운로드해 디스크에 기록하는 정확한 파일 목록입니다. 경로에 하위 디렉터리를 포함할 수 있습니다:

JSON
{
  "files": [
    "block.json",
    "index.php",
    "style.scss",
    "src/components/tabs.tsx",
    "src/styles/tabs.css"
  ]
}

파일 경로 확인

블록 매니페스트의 각 파일에 대해 CLI은 다운로드 URL를 구성합니다:

코드
{baseUrl}/{block.name}/{file}

그리고 다음 위치에 기록합니다:

코드
{directory}/{block.name}/{file}

블록 폴더 내부의 디렉터리 구조는 유지됩니다. 파일 경로에 하위 디렉터리가 있으면 자동으로 생성됩니다.

파일은 항상 registry.json 안의 baseUrl에서 가져옵니다. blocks.json의 레지스트리 URL를 기준으로 한 상대 위치에서 가져오지 않습니다.

유효성 검사

CLI은 가져올 때마다 registry.json을 Zod 스키마에 따라 검증합니다. 유효하지 않은 레지스트리가 있으면 검증에 실패한 구체적인 필드를 명시하는 오류 메시지를 표시합니다.

누락된 필수 필드, 비어 있는 blocks 또는 files 배열, 유효하지 않은 URL 및 알 수 없는 type 값은 파일을 다운로드하기 전에 모두 감지됩니다.