Saltar al contenido

Publicar un registro de bloques en GitHub

Cuando haya creado algunos bloques útiles, querrá reutilizarlos en el siguiente proyecto. Copiar carpetas manualmente entre temas funciona hasta que las copias divergen y nadie recuerda qué tema tiene la versión corregida. Envolver cada bloque en un paquete con su propia compilación supone demasiada ceremonia para una carpeta que contiene un block.json y una plantilla.

Un registro de bloques ofrece una solución intermedia. Es un archivo registry.json y un conjunto de carpetas de bloques que se sirven mediante HTTP sin procesar. Los usuarios ejecutan un comando CLI, el código fuente del bloque se copia en su tema y, a partir de ahí, esa copia les pertenece. Un repositorio GitHub basta para alojarlo, porque GitHub sirve todos los archivos de un repositorio público en una URL sin procesar.

Esta guía crea un registro llamado acme con cuatro bloques, lo publica desde el repositorio acme/acme-blocks, instala bloques desde él en un tema y fija una versión mediante una etiqueta de git.

El paquete blockstudio en npm está en la versión 0.0.1. Esa versión es un marcador de posición: su único comando, add, muestra Adding block: <name> y termina sin descargar nada. Los comandos y resultados de esta guía proceden del registro CLI en el repositorio Blockstudio (packages/registry), que es el CLI descrito en la documentación del registro.

Cómo encajan las piezas

Hay dos archivos que debe conocer:

  • registry.json lo publica el autor del bloque. Enumera los bloques, los archivos que componen cada uno y un baseUrl para descargarlos.
  • blocks.json está en el tema o plugin del usuario. Indica qué registros se usarán y en qué directorio se instalarán los bloques.

Al instalar un bloque, CLI consulta todos los registros de blocks.json, busca el bloque, resuelve sus dependencias, descarga cada archivo indicado desde {baseUrl}/{block}/{file} y lo guarda en {directory}/{block}/{file}. No transforma nada, así que los archivos del disco son exactamente los del repositorio.

Paso 1: Estructure el repositorio

Cree un repositorio con un registry.json en la raíz y una carpeta por bloque dentro de blocks/:

Código
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

El nombre de la carpeta es el nombre del bloque en el registro y pasa a ser el nombre de la carpeta en el tema del usuario. Manténgalo idéntico a la segunda parte del nombre del bloque en block.json (acme/hero está en hero/) para que sea fácil reconocer la carpeta instalada.

Paso 2: Escriba los bloques

Cada carpeta contiene un bloque Blockstudio común. El bloque de sección principal tiene un campo:

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 sigue el mismo patrón y añade un style.scss. tabs renderiza <InnerBlocks allowedBlocks='["acme/tab-item"]' /> y tab-item declara "parent": ["acme/tabs"], por lo que tabs no resulta útil sin tab-item. El registro expresa esa relación en el paso siguiente.

Estos bloques no tienen nada específico del registro. CLI copia carpetas, así que un bloque creado con @wordpress/create-block o registrado con PHP sin más puede publicarse del mismo modo.

Paso 3: Escriba registry.json

registry.json enumera todos los bloques y archivos que CLI debe descargar:

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

Unas cuantas reglas determinan si este archivo funciona:

  • files es una lista explícita. CLI descarga exactamente estas rutas y nada más. No hay expansión de patrones, así que un recurso nuevo solo se incluirá cuando lo añada aquí. Las rutas pueden contener subdirectorios, que se crean durante la instalación.
  • baseUrl debe ser un URL absoluto. CLI lo valida como URL y rechaza los valores relativos. Los archivos de bloque siempre se obtienen de baseUrl, nunca de una ubicación relativa al lugar desde el que se haya cargado registry.json.
  • dependencies nombra los bloques del mismo registro. Añadir tabs instala primero tab-item. Las dependencias que faltan o son circulares detienen la instalación y muestran un error.
  • name es obligatorio, pero no se muestra. Los comandos y la salida usan la clave que el consumidor asigna al registro en blocks.json; no tienen que coincidir.
  • type es informativo. Acepta blockstudio, create-block o wordpress, y no cambia lo que hace CLI.

CLI valida el archivo completo en cada descarga e indica cada campo que falla, así que un error tipográfico se detecta antes de descargar ningún archivo. La línea $schema aplica las mismas comprobaciones en el editor.

Paso 4: Publicar mediante URL sin procesar

Confirme los cambios y suba el repositorio a GitHub. A partir de entonces, todos los archivos de un repositorio público estarán disponibles en:

Código
https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

<ref> es una rama, una etiqueta o un SHA de confirmación. Para este registro, hay dos URL importantes:

  • El URL que configuran los consumidores: https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json
  • El baseUrl en registry.json: https://raw.githubusercontent.com/acme/acme-blocks/main/blocks

Con ese baseUrl, index.php de hero se obtiene de https://raw.githubusercontent.com/acme/acme-blocks/main/blocks/hero/index.php. El servidor de archivos sin procesar devuelve el contenido del archivo en lugar de la página GitHub HTML, que es lo que necesita CLI. Si el propietario, el repositorio o la referencia son incorrectos, se mostrará un 404 con el primer comando:

Código
Registry returned 404 for https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json

Paso 5: Instalar bloques en un tema

En la raíz del tema consumidor, cree blocks.json:

Shell
npx blockstudio init --yes
Código
Created .../acme-theme/blocks.json

init --yes escribe un objeto registries vacío. Añada el registro bajo el espacio de nombres que quiera escribir en los comandos:

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

Ejecute init sin --yes en una terminal para responder de forma interactiva a las mismas preguntas (directorio de bloques, nombres y URL de registros).

Compruebe que se encuentra el registro:

Shell
npx blockstudio list
Código
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 busca una subcadena sin distinguir mayúsculas de minúsculas en nombres, títulos y descripciones:

Shell
npx blockstudio search tab
Código
Results for "tab"

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

Obtenga una vista previa de la instalación con --dry-run. La dependencia aparece primero porque también se instala primero:

Shell
npx blockstudio add acme/tabs --dry-run
Código
Would install:
  tab-item (2 files)
  tabs (3 files)

Ahora instálelo de verdad:

Shell
npx blockstudio add acme/tabs
Código
Downloading acme/tabs...
Installed tab-item (2 files)
Installed tabs (3 files)

Ahora ambas carpetas están en el directorio blockstudio del tema, exactamente como aparecen en el repositorio:

Código
blockstudio/tab-item/block.json
blockstudio/tab-item/index.php
blockstudio/tabs/block.json
blockstudio/tabs/index.php
blockstudio/tabs/style.scss

Puede omitir el espacio de nombres cuando solo un registro configurado contiene el bloque y pasar varios bloques a la vez:

Shell
npx blockstudio add hero card
Código
Downloading acme/hero...
Installed hero (2 files)
Downloading acme/card...
Installed card (3 files)

Blockstudio detecta las carpetas nuevas como cualquier otro bloque del tema.

Actualizar bloques instalados

Los archivos instalados son una copia. No se registra qué versión instaló y CLI nunca actualiza un bloque por su cuenta. Para obtener una versión más reciente, vuelva a añadir el bloque. Si no usa una terminal o ejecuta el comando en CI, una carpeta existente detiene el comando:

Shell
npx blockstudio add tab-item
Código
Block "tab-item" already exists at .../acme-theme/blockstudio/tab-item. Use --yes to overwrite.

En una terminal, CLI pregunta antes de sobrescribir. --dry-run muestra las carpetas que reemplazaría y --yes las reemplaza:

Shell
npx blockstudio add acme/tab-item --dry-run
Código
Would overwrite tab-item
Would install:
  tab-item (2 files)

Al sobrescribir, los archivos indicados se reemplazan por la versión del registro. Confirme primero los cambios locales y revise el resultado con git diff.

Para desinstalarlo, elimine la carpeta por nombre:

Shell
npx blockstudio remove tabs --yes
Código
Removed tabs

remove recibe el nombre de la carpeta, no namespace/block. No elimina las dependencias, así que tab-item seguirá instalado después de eliminar tabs.

Control de versiones con referencias de git

CLI no tiene un campo de versión ni una opción de versión. Lo que descarga depende por completo de las URL y, en GitHub, la referencia de URL es la versión. Si un consumidor apunta a main, obtendrá lo que contenga main en el momento de la instalación.

Para publicar una versión que permanezca fija, registry.json de la etiqueta también debe descargar desde esa etiqueta. Antes de crearla, establezca baseUrl con la etiqueta:

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

Después, confirme los cambios, cree la etiqueta y súbalos:

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

Después, vuelva a establecer baseUrl como main y confirme los cambios para que la rama siga ofreciendo los archivos actuales. Si omite el primer paso, un consumidor fijado a la etiqueta obtendrá la lista de bloques etiquetada, pero descargará los archivos de main.

Los consumidores fijan la versión usando la etiqueta en el URL de su registro:

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

En este ejemplo, v1.0.0 se etiquetó antes de que existieran tabs y tab-item, por lo que el registro fijado solo ofrece los dos bloques originales:

Shell
npx blockstudio list
Código
acme (2 blocks)

  Name  Title  Category      Type
  hero  Hero   layout        blockstudio
  card  Card   components    blockstudio
Shell
npx blockstudio add acme/tabs
Código
Block "tabs" not found in registry "acme".

También se puede usar un SHA de confirmación en el URL del registro, pero una confirmación no puede contener su propio SHA en baseUrl. Por tanto, fijar la versión mediante un SHA fija la lista de bloques, pero los archivos siguen procediendo de la referencia que indique baseUrl de esa confirmación. Por eso se recomienda usar etiquetas para las versiones.

Aspectos que conviene tener en cuenta

  • Primero se obtienen todos los registros. add carga todos los registros en blocks.json antes de resolver nada, así que un registro inaccesible hace que el comando falle incluso para acme/hero. Elimine los registros que ya no use.
  • Los nombres ambiguos necesitan un espacio de nombres. Si dos registros tienen hero, una sesión de terminal pregunta cuál usar, --yes toma el primero en el orden blocks.json y una ejecución no interactiva termina con Block "hero" found in multiple registries: acme, starter. Specify one: blockstudio add acme/hero.
  • Los repositorios privados necesitan encabezados. Use el formato de objeto para una entrada de registro con url y headers. Los valores de encabezado admiten marcadores de posición ${VAR} que se leen del entorno, y CLI envía los encabezados al obtener el registro y al descargar cada archivo. Consulte alojamientoGitHub para configurar el token.

Pasos siguientes