Paquetes de Blueprint

Los paquetes de Blueprint son paquetes autocontenidos que incluyen una declaración de Blueprint (blueprint.json) junto con todos los recursos adicionales necesarios para compilarlo y ejecutarlo. Así es más fácil distribuir y compartir configuraciones completas de WordPress Playground.

¿Qué son los paquetes de Blueprint?

Un paquete de Blueprint es una colección de archivos que incluye:

1. Un archivo blueprint.json que define la configuración del Blueprint
2. Cualquier recurso adicional al que haga referencia el Blueprint (temas, plugins, archivos de contenido, etc.)

Los paquetes de Blueprint pueden distribuirse en varios formatos:

• Un archivo ZIP con un blueprint.json en el nivel superior y recursos adicionales
• Un directorio dentro de un repositorio git donde blueprint.json convive con otros recursos
• Un directorio local en tu equipo
• Un objeto JavaScript en línea con los archivos pertinentes incrustados

Uso de paquetes de Blueprint

En el sitio web

El sitio de WordPress Playground admite paquetes de Blueprint mediante el parámetro de consulta ?blueprint-url=. Puedes indicar la URL de un archivo ZIP con tu paquete de Blueprint:

https://playground.wordpress.net/?blueprint-url=https://example.com/my-blueprint-bundle.zip

El archivo ZIP debe incluir un blueprint.json en la raíz, junto con los recursos adicionales a los que haga referencia el Blueprint.

En la CLI

Playground CLI admite paquetes de Blueprint mediante la opción --blueprint=. Puedes indicar:

• La ruta a un directorio local que contenga un paquete de Blueprint
• La ruta a un archivo ZIP local que contenga un paquete de Blueprint
• La URL de un paquete de Blueprint remoto (http:// o https://)

Por ejemplo:

# Using a local ZIP file
npx @wp-playground/cli --blueprint=./my-blueprint.zip server

# Using a remote URL
npx @wp-playground/cli --blueprint=https://example.com/my-blueprint.zip server

# Using a local directory
npx @wp-playground/cli --blueprint=./my-blueprint-directory server

Por defecto, la CLI restringe el acceso a archivos locales por seguridad. Si tu Blueprint necesita leer archivos en el mismo directorio padre, debes conceder permiso explícitamente con la opción --blueprint-may-read-adjacent-files:

npx @wp-playground/cli --blueprint=./my-blueprint.json --blueprint-may-read-adjacent-files server

Crear paquetes de Blueprint

Estructura básica

Un paquete de Blueprint básico puede tener este aspecto:

my-blueprint-bundle/
├── blueprint.json
├── theme.zip
├── plugin.zip
└── content/
    └── sample-content.wxr

Ejemplo de Blueprint con recursos incluidos

Aquí tienes un ejemplo de archivo blueprint.json que referencia recursos incluidos en el paquete:

{
	"landingPage": "/my-file.txt",
	"steps": [
		{
			"step": "writeFile",
			"path": "/wordpress/my-file.txt",
			"data": {
				"resource": "bundled",
				"path": "/bundled-text-file.txt"
			}
		},
		{
			"step": "installTheme",
			"themeData": {
				"resource": "bundled",
				"path": "/theme.zip"
			}
		},
		{
			"step": "installPlugin",
			"pluginData": {
				"resource": "bundled",
				"path": "/plugin.zip"
			}
		},
		{
			"step": "importWxr",
			"file": {
				"resource": "bundled",
				"path": "/content/sample-content.wxr"
			}
		}
	]
}

En este ejemplo, el Blueprint referencia varios recursos incluidos:

• Un archivo de texto en /bundled-text-file.txt
• Un ZIP de tema en /theme.zip
• Un ZIP de plugin en /plugin.zip
• Un archivo de contenido WXR en /content/sample-content.wxr

Crear un paquete ZIP

Para crear un paquete ZIP, crea un directorio con tu blueprint.json y todos los recursos necesarios y comprímelo:

# Create a directory for your bundle
mkdir my-blueprint-bundle
cd my-blueprint-bundle

# Create your blueprint.json and add resources
# ...

# Zip it up
zip -r ../my-blueprint-bundle.zip .

Flexibilidad en la estructura del ZIP

Los paquetes de Blueprint admiten blueprint.json en dos ubicaciones dentro de un archivo ZIP:

1. En la raíz (habitual): blueprint.json está directamente en la raíz del ZIP
2. Un nivel de carpeta: blueprint.json está dentro de un único directorio de primer nivel

Así, los ZIP creados con «Comprimir» del menú contextual en macOS (que envuelven el contenido en una carpeta) funcionan sin pasos extra. El directorio de metadatos __MACOSX se ignora al detectar el Blueprint.

Ejemplo: estas dos estructuras de ZIP son válidas:

# Structure A (root level)
my-bundle.zip/
├── blueprint.json
├── theme.zip
└── plugin.zip

# Structure B (one directory deep — macOS-style)
my-bundle.zip/
├── my-bundle/
│   ├── blueprint.json
│   ├── theme.zip
│   └── plugin.zip
└── __MACOSX/         ← ignored

Si varios directorios de primer nivel contienen un blueprint.json, Playground devuelve un error para evitar ambigüedades.

Solución de problemas

Si tienes problemas con los paquetes de Blueprint:

1. Comprueba que blueprint.json esté en la raíz del ZIP o dentro de un único directorio de primer nivel
2. Verifica que las rutas en las referencias a recursos incluidos sean correctas
3. Comprueba que el ZIP esté bien formado
4. Si usas la CLI, comprueba si necesitas la opción --blueprint-may-read-adjacent-files
5. Asegúrate de que el paquete incluye todos los recursos necesarios