본문으로 건너뛰기

GitHub에서 블록 레지스트리 게시하기

괜찮은 블록을 몇 개 만들고 나면 다음 프로젝트에서도 사용하고 싶어집니다. 테마 간에 폴더를 직접 복사하는 방법은 복사본이 서로 달라지고 어느 테마에 수정 버전이 있는지 아무도 기억하지 못하게 되기 전까지만 유효합니다. 블록마다 자체 빌드가 있는 패키지로 감싸는 방식은 block.json와 템플릿이 들어 있는 폴더치고는 절차가 지나치게 복잡합니다.

블록 레지스트리는 그 중간에 있습니다. registry.json 파일과 블록 폴더 모음으로 구성되며 일반 HTTP을 통해 제공됩니다. 사용자가 CLI 명령을 실행하면 블록 소스가 테마에 복사되고, 그 뒤로는 복사본을 직접 관리합니다. GitHub 저장소면 호스팅에 충분합니다. GitHub는 공개 저장소의 모든 파일을 원시 URL로 제공하기 때문입니다.

이 가이드에서는 acme라는 레지스트리를 네 개의 블록으로 만들고, 저장소 acme/acme-blocks에서 게시한 뒤, 여기서 블록을 테마에 설치하고 git 태그로 릴리스를 고정합니다.

blockstudio 패키지는 npm에서 버전 0.0.1입니다. 해당 릴리스는 자리표시자입니다. 유일한 명령인 add은 Adding block: <name>를 출력하고 아무것도 가져오지 않은 채 종료합니다. 이 가이드의 명령과 출력은 저장소 Blockstudio의 레지스트리 CLI(packages/registry)에서 가져온 것으로, 레지스트리 문서에서 설명하는 CLI입니다.

구성 요소의 연결 방식

알아둘 파일은 두 개입니다.

  • registry.json은 블록 제작자가 게시합니다. 블록 목록, 각 블록을 구성하는 파일, 파일을 내려받을 baseUrl이 들어 있습니다.
  • blocks.json는 사용자의 테마나 플러그인에 있습니다. 사용할 레지스트리와 블록을 설치할 디렉터리를 지정합니다.

블록을 설치하면 CLI이 blocks.json에 지정된 모든 레지스트리를 가져와 블록을 찾고, 종속성을 확인하고, 각 파일을 {baseUrl}/{block}/{file}에서 내려받아 {directory}/{block}/{file}에 씁니다. 파일을 변환하지 않으므로 디스크에 저장되는 파일은 저장소의 파일과 정확히 같습니다.

1단계: 저장소 구성하기

루트에 registry.json을 두고 blocks/ 아래에 블록별 폴더를 하나씩 만들어 저장소를 구성합니다.

코드
acme-blocks/
  registry.json
  blocks/
    hero/
      block.json
      index.php
    card/
      block.json
      index.php
      style.scss
    tabs/
      block.json
      index.php
      style.scss
    tab-item/
      block.json
      index.php

폴더 이름은 레지스트리에서 블록 이름으로 사용되며 사용자의 테마에 설치될 때도 폴더 이름이 됩니다. block.json에 있는 블록 이름의 두 번째 부분과 동일하게 지정하세요(acme/hero은 hero/에 있습니다). 그래야 설치된 폴더를 쉽게 알아볼 수 있습니다.

2단계: 블록 작성하기

각 폴더는 일반적인 Blockstudio 블록입니다. 히어로 블록에는 필드가 하나 있습니다.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "category": "design",
  "blockstudio": {
    "attributes": [
      {
        "id": "heading",
        "type": "text",
        "label": "Heading",
        "default": "Build faster"
      }
    ]
  }
}
PHP
<section useBlockProps class="acme-hero">
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
</section>

card은 같은 패턴을 따르며 style.scss을 추가합니다. tabs는 <InnerBlocks allowedBlocks='["acme/tab-item"]' />을 렌더링하고, tab-item는 "parent": ["acme/tabs"]를 선언하므로 tabs은 tab-item 없이는 쓸모가 없습니다. 다음 단계에서 레지스트리에 이 관계를 표현합니다.

이 블록은 레지스트리 전용이 아닙니다. CLI은 폴더를 복사하므로 @wordpress/create-block으로 만들거나 일반 PHP로 등록한 블록도 같은 방식으로 게시할 수 있습니다.

3단계: registry.json 작성하기

registry.json에는 레지스트리에 표시할 모든 블록과 CLI에서 내려받을 각 파일이 나열됩니다.

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "acme",
  "description": "Acme block library.",
  "baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
  "blocks": [
    {
      "name": "hero",
      "title": "Hero",
      "description": "Full-width hero section with a heading.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    },
    {
      "name": "card",
      "title": "Card",
      "description": "Content card with a title.",
      "category": "components",
      "type": "blockstudio",
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": ["block.json", "index.php", "style.scss"]
    },
    {
      "name": "tab-item",
      "title": "Tab Item",
      "description": "Single tab panel used inside Tabs.",
      "category": "layout",
      "type": "blockstudio",
      "files": ["block.json", "index.php"]
    }
  ]
}

이 파일의 작동 여부를 결정하는 몇 가지 규칙이 있습니다.

  • files은 명시적인 목록입니다. CLI은 여기에 지정된 경로만 다운로드하며 다른 항목은 가져오지 않습니다. glob 패턴을 사용하지 않으므로 새 에셋은 여기에 추가해야 배포됩니다. 경로에 하위 디렉터리가 포함될 수 있으며, 설치 시 생성됩니다.
  • baseUrl은 절대 URL이어야 합니다. CLI은 이를 URL로 검증하고 상대 경로 값은 거부합니다. 블록 파일은 항상 baseUrl에서 가져오며, registry.json이 로드된 위치를 기준으로 가져오지 않습니다.
  • dependencies은 같은 레지스트리에 블록 이름을 지정해야 합니다. tabs을 추가하면 먼저 tab-item이 설치됩니다. 누락되거나 순환하는 종속성이 있으면 설치가 오류와 함께 중단됩니다.
  • name은 필수 항목이지만 표시되지는 않습니다. 명령과 출력에는 사용자가 레지스트리에 지정한 키인 blocks.json을 사용하며, 이 키는 일치하지 않아도 됩니다.
  • type은 참고용입니다. blockstudio, create-block 또는 wordpress을 허용하며, CLI의 동작에는 영향을 주지 않습니다.

CLI은 파일을 가져올 때마다 파일 전체를 검증하고 실패한 각 필드를 알려 주므로, 오타가 있으면 파일을 다운로드하기 전에 확인할 수 있습니다. $schema 줄을 사용하면 편집기에서도 같은 검사를 받을 수 있습니다.

4단계: raw URL로 게시하기

저장소를 GitHub에 커밋하고 푸시합니다. 그러면 공개 저장소의 모든 파일을 다음 주소에서 사용할 수 있습니다:

코드
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref>은 브랜치, 태그 또는 커밋 SHA입니다. 이 레지스트리에서 중요한 URL은 두 가지입니다:

  • 소비자가 설정하는 레지스트리 URL: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • registry.json의 baseUrl: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

이 baseUrl을 사용하면 hero의 index.php을 https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php에서 가져옵니다. raw 호스트는 GitHub HTML 페이지 대신 파일 내용을 반환하며, 이는 CLI에 필요한 동작입니다. 소유자, 저장소 또는 ref가 잘못되면 첫 명령에서 404이 발생합니다:

코드
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

5단계: 테마에 블록 설치하기

소비 테마의 루트에서 blocks.json을 만듭니다:

셸
npx blockstudio init --yes
코드
Created .../acme-theme/blocks.json

init --yes은 빈 registries 객체를 만듭니다. 명령에서 입력할 네임스페이스 아래에 레지스트리를 추가합니다:

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

터미널에서 --yes 없이 init을 실행하면 블록 디렉터리, 레지스트리 이름, URL에 관한 같은 질문에 대화형으로 답할 수 있습니다.

레지스트리가 확인되는지 검사합니다:

셸
npx blockstudio list
코드
acme (4 blocks)

  Name      Title     Category      Type
  hero      Hero      layout        blockstudio
  card      Card      components    blockstudio
  tabs      Tabs      layout        blockstudio
  tab-item  Tab Item  layout        blockstudio

search은 이름, 제목, 설명에서 대소문자를 구분하지 않는 부분 문자열을 찾습니다:

셸
npx blockstudio search tab
코드
Results for "tab"

  acme/tabs - Tabs
    Tabbed content with keyboard navigation.
  acme/tab-item - Tab Item
    Single tab panel used inside Tabs.

--dry-run으로 설치를 미리 봅니다. 종속 항목은 먼저 설치되므로 목록에서도 먼저 표시됩니다:

셸
npx blockstudio add acme/tabs --dry-run
코드
Would install:
  tab-item (2 files)
  tabs (3 files)

그런 다음 실제로 설치합니다:

셸
npx blockstudio add acme/tabs
코드
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

이제 두 폴더가 저장소에 있는 그대로 테마의 blockstudio 디렉터리에 있습니다:

코드
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

설정된 레지스트리 중 하나에만 해당 블록이 있으면 네임스페이스를 생략할 수 있으며, 한 번에 여러 블록을 전달할 수도 있습니다:

셸
npx blockstudio add hero card
코드
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio은 테마의 다른 블록과 마찬가지로 새 폴더를 찾습니다.

설치된 블록 업데이트하기

설치된 파일은 복사본입니다. 설치한 버전은 추적되지 않으며, CLI은 블록을 자동으로 업데이트하지 않습니다. 새 버전을 가져오려면 블록을 다시 추가하세요. 터미널을 사용하지 않거나 CI에서 실행할 때 기존 폴더가 있으면 명령이 중단됩니다:

셸
npx blockstudio add tab-item
코드
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

터미널에서는 덮어쓰기 전에 CLI이 확인을 요청합니다. --dry-run은 대체할 폴더를 알려 주고, --yes는 해당 폴더를 대체합니다:

셸
npx blockstudio add acme/tab-item --dry-run
코드
Would overwrite tab-item
Would install:
  tab-item (2 files)

덮어쓰면 목록에 있는 파일이 레지스트리 버전으로 대체되므로, 먼저 로컬 변경 사항을 커밋하고 git diff으로 결과를 검토하세요.

제거하려면 이름으로 폴더를 삭제합니다:

셸
npx blockstudio remove tabs --yes
코드
Removed tabs

remove에는 namespace/block이 아니라 폴더 이름을 전달합니다. 종속 항목은 제거하지 않으므로 tabs을 제거한 후에도 tab-item는 설치된 상태로 유지됩니다.

git ref를 사용한 버전 관리

CLI에는 버전 필드나 버전 플래그가 없습니다. 가져오는 내용은 전적으로 URL에 따라 결정되며, GitHub에서는 URL의 ref가 버전입니다. main을 지정한 소비자는 설치 시점에 main에 있는 내용을 가져옵니다.

고정된 상태로 유지되는 릴리스를 게시하려면 태그의 registry.json도 해당 태그에서 다운로드하도록 해야 합니다. 태그를 만들기 전에 baseUrl을 태그로 설정합니다:

JSON
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"

그런 다음 커밋하고 태그를 만든 뒤 푸시합니다:

셸
git commit -am 'Release v1.0.0'
git tag v1.0.0
git push origin main v1.0.0

그 후 baseUrl을 다시 main로 설정하고 커밋하면 브랜치가 최신 파일을 계속 제공합니다. 첫 단계를 건너뛰면 태그를 고정한 소비자는 태그의 블록 목록을 받지만 파일은 main에서 다운로드합니다.

소비자는 레지스트리 URL에 태그를 사용해 버전을 고정합니다:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
  }
}

이 예제에서는 v1.0.0이 tabs과 tab-item가 존재하기 전에 태그가 만들어졌으므로, 고정된 레지스트리에는 원래 블록 두 개만 표시됩니다:

셸
npx blockstudio list
코드
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
셸
npx blockstudio add acme/tabs
코드
Block "tabs" not found in registry "acme".

커밋 SHA를 레지스트리 URL에 사용할 수도 있지만, 커밋에는 자체 SHA를 baseUrl에 포함할 수 없습니다. 따라서 SHA로 고정하면 블록 목록은 고정되지만 파일은 해당 커밋의 baseUrl이 가리키는 ref에서 가져옵니다. 릴리스에는 태그를 사용하는 것이 좋습니다.

유의할 점

  • 모든 레지스트리를 먼저 가져옵니다. add은 무엇이든 확인하기 전에 blocks.json의 모든 레지스트리를 불러오므로, 연결할 수 없는 레지스트리가 하나라도 있으면 acme/hero에 대해서도 명령이 실패합니다. 더 이상 사용하지 않는 레지스트리는 제거하세요.
  • 이름이 중복되면 네임스페이스가 필요합니다. 두 레지스트리에 모두 hero이 있으면 터미널 세션에서 사용할 레지스트리를 묻고, --yes는 blocks.json 순서에서 첫 항목을 사용하며, 비대화형 실행은 Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero과 함께 종료됩니다.
  • 비공개 저장소에는 헤더가 필요합니다. 레지스트리 항목의 객체 형식에 url과 headers을 사용하세요. 헤더 값에서는 환경 변수에서 읽어 오는 ${VAR} 플레이스홀더를 사용할 수 있으며, CLI은 레지스트리를 가져올 때와 각 파일을 다운로드할 때 헤더를 전송합니다. 토큰 설정은 GitHub호스팅을 참조하세요.

다음 단계