Pacotes de Blueprint

Pacotes de Blueprint são pacotes autocontidos que incluem uma declaração de Blueprint (blueprint.json) e todos os recursos adicionais necessários para compilá-lo e executá-lo. Isso facilita distribuir e compartilhar configurações completas do WordPress Playground.

O que são pacotes de Blueprint?

Um pacote de Blueprint é uma coleção de arquivos que inclui:

1. Um arquivo blueprint.json que define a configuração do Blueprint
2. Quaisquer recursos adicionais referenciados pelo Blueprint (temas, plugins, arquivos de conteúdo, etc.)

Pacotes de Blueprint podem ser distribuídos em vários formatos:

• Um arquivo ZIP com blueprint.json no nível superior e recursos adicionais
• Um diretório dentro de um repositório git em que o blueprint.json fica junto dos demais recursos
• Um diretório local no seu computador
• Um objeto JavaScript inline com os arquivos relevantes embutidos

Usar pacotes de Blueprint

No site

O site do WordPress Playground aceita pacotes de Blueprint pelo parâmetro de consulta ?blueprint-url=. Você pode informar a URL de um arquivo ZIP com o seu pacote:

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

O ZIP deve conter um blueprint.json na raiz, além dos recursos adicionais referenciados pelo Blueprint.

Na CLI

O Playground CLI aceita pacotes de Blueprint pela opção --blueprint=. Você pode informar:

• Caminho para um diretório local com um pacote de Blueprint
• Caminho para um arquivo ZIP local com um pacote de Blueprint
• URL de um pacote remoto (http:// ou https://)

Por exemplo:

# 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 padrão, a CLI restringe o acesso a arquivos locais por segurança. Se o Blueprint precisar ler arquivos no mesmo diretório pai, conceda permissão com a flag --blueprint-may-read-adjacent-files:

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

Criar pacotes de Blueprint

Estrutura básica

Um pacote de Blueprint básico pode ser assim:

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

Exemplo de Blueprint com recursos empacotados

Exemplo de blueprint.json que referencia recursos empacotados:

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

Neste exemplo, o Blueprint referencia vários recursos empacotados:

• Arquivo de texto em /bundled-text-file.txt
• ZIP do tema em /theme.zip
• ZIP do plugin em /plugin.zip
• Arquivo de conteúdo WXR em /content/sample-content.wxr

Criar um pacote ZIP

Para criar um pacote ZIP, crie um diretório com o blueprint.json e todos os recursos necessários e compacte:

# 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 .

Flexibilidade da estrutura do ZIP

Pacotes de Blueprint aceitam blueprint.json em dois locais dentro do ZIP:

1. Na raiz (padrão): blueprint.json fica diretamente na raiz do ZIP
2. Um nível de pasta: blueprint.json fica dentro de um único diretório de primeiro nível

Assim, ZIPs criados com «Comprimir» no macOS (que envolvem o conteúdo em uma pasta) funcionam automaticamente. O diretório de metadados __MACOSX é ignorado na detecção.

Exemplo: estas duas estruturas de ZIP funcionam:

# 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

Se vários diretórios de primeiro nível contiverem blueprint.json, o Playground retorna um erro para evitar ambiguidade.

Solução de problemas

Se tiver problemas com pacotes de Blueprint:

1. Confira se o blueprint.json está na raiz do ZIP ou dentro de um único diretório de primeiro nível
2. Verifique se os caminhos nas referências a recursos empacotados estão corretos
3. Confirme se o ZIP está bem formado
4. Na CLI, veja se precisa da flag --blueprint-may-read-adjacent-files
5. Garanta que todos os recursos necessários estão no pacote