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.jsonlo publica el autor del bloque. Enumera los bloques, los archivos que componen cada uno y unbaseUrlpara descargarlos.blocks.jsonestá 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/:
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:
{
"$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"
}
]
}
}
<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:
{
"$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:
fileses 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.baseUrldebe ser un URL absoluto. CLI lo valida como URL y rechaza los valores relativos. Los archivos de bloque siempre se obtienen debaseUrl, nunca de una ubicación relativa al lugar desde el que se haya cargadoregistry.json.dependenciesnombra los bloques del mismo registro. Añadirtabsinstala primerotab-item. Las dependencias que faltan o son circulares detienen la instalación y muestran un error.namees obligatorio, pero no se muestra. Los comandos y la salida usan la clave que el consumidor asigna al registro enblocks.json; no tienen que coincidir.typees informativo. Aceptablockstudio,create-blockowordpress, 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:
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
baseUrlenregistry.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:
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:
npx blockstudio init --yes
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:
{
"$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:
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 busca una subcadena sin distinguir mayúsculas de minúsculas en nombres, títulos y descripciones:
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.
Obtenga una vista previa de la instalación con --dry-run. La dependencia aparece primero porque también se instala primero:
npx blockstudio add acme/tabs --dry-run
Would install:
tab-item (2 files)
tabs (3 files)
Ahora instálelo de verdad:
npx blockstudio add acme/tabs
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:
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:
npx blockstudio add hero card
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:
npx blockstudio add tab-item
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:
npx blockstudio add acme/tab-item --dry-run
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:
npx blockstudio remove tabs --yes
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:
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/blocks"
Después, confirme los cambios, cree la etiqueta y súbalos:
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:
{
"$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:
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".
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.
addcarga todos los registros enblocks.jsonantes de resolver nada, así que un registro inaccesible hace que el comando falle incluso paraacme/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,--yestoma el primero en el ordenblocks.jsony una ejecución no interactiva termina conBlock "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
urlyheaders. 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
- Descripción general del registro: qué es el registro y cómo funciona CLI
- registry.json: todos los campos del manifiesto
- blocks.json: configuración del consumidor, autenticación y detección de configuración
- add: resolución de espacios de nombres, dependencias y comportamiento al sobrescribir
- GitHub hosting: GitHub Pages y repositorios privados
- Servidor personalizado: alojar un registro en su propia infraestructura