Paquets Blueprint

Les paquets Blueprint sont des dépendances autonomes qui contiennent une déclaration Blueprint (blueprint.json) ainsi que toutes les ressources supplémentaires nécessaires pour le compiler et l’exécuter. Cela facilite la distribution et le partage d’installations WordPress Playground complètes.

Qu’est-ce qu’un paquet Blueprint ?

Un paquet Blueprint est un ensemble de fichiers qui comprend :

Un fichier blueprint.json qui définit la configuration du Blueprint
Toutes les ressources supplémentaires référencées par le Blueprint (thèmes, extensions, fichiers de contenu, etc.)

Les paquets Blueprint peuvent être distribués sous plusieurs formes :

Un fichier ZIP avec un fichier blueprint.json à la racine et des ressources supplémentaires
Un répertoire dans un dépôt Git où un fichier blueprint.json se trouve à côté des autres ressources
Un répertoire local sur votre ordinateur
Un objet JavaScript intégré avec les fichiers pertinents incorporés

Utiliser les paquets Blueprint

Sur le site

Le site WordPress Playground prend en charge les paquets Blueprint via le paramètre de requête ?blueprint-url=. Vous pouvez fournir l’URL d’un fichier ZIP contenant votre paquet Blueprint :

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

Le fichier ZIP doit contenir un fichier blueprint.json à la racine, ainsi que toutes les ressources supplémentaires référencées par le Blueprint.

Dans la CLI

Playground CLI prend en charge les paquets Blueprint via l’option --blueprint=. Vous pouvez indiquer :

Le chemin vers un répertoire local contenant un paquet Blueprint
Le chemin vers un fichier ZIP local contenant un paquet Blueprint
L’URL d’un paquet Blueprint distant (http:// ou https://)

Par exemple :

# 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

Par défaut, la CLI limite l’accès aux fichiers locaux pour des raisons de sécurité. Si votre Blueprint doit accéder à des fichiers dans le même répertoire parent, vous devez l’autoriser explicitement avec le drapeau --blueprint-may-read-adjacent-files :

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

Créer des paquets Blueprint

Structure de base

Un paquet Blueprint basique peut ressembler à ceci :

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

Exemple de Blueprint avec ressources groupées

Voici un exemple de fichier blueprint.json qui référence des ressources groupées :

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

Dans cet exemple, le Blueprint référence plusieurs ressources groupées :

Un fichier texte à /bundled-text-file.txt
Un fichier ZIP de thème à /theme.zip
Un fichier ZIP d’extension à /plugin.zip
Un fichier de contenu WXR à /content/sample-content.wxr

Créer un paquet ZIP

Pour créer un paquet ZIP, créez un répertoire avec votre blueprint.json et toutes les ressources requises, puis compressez-le :

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

Souplesse de la structure des fichiers ZIP

Les paquets Blueprint acceptent blueprint.json à deux emplacements dans un fichier ZIP :

À la racine (habituel) : blueprint.json est directement à la racine du ZIP
Un niveau de dossier : le fichier blueprint.json se trouve dans un seul répertoire de premier niveau

Ainsi, les ZIP créés avec « Compresser » au clic droit sous macOS (qui enveloppent le contenu dans un dossier) fonctionnent automatiquement. Le dossier de métadonnées __MACOSX est ignoré lors de la détection.

Exemple : ces deux structures ZIP conviennent :

# 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 plusieurs répertoires de premier niveau contiennent un blueprint.json, Playground renvoie une erreur pour éviter toute ambiguïté.

Dépannage

En cas de problème avec les paquets Blueprint :

Vérifiez que le fichier blueprint.json se trouve à la racine du ZIP ou dans un seul répertoire de premier niveau
Contrôlez l'exactitude des chemins référençant les ressources groupées
Vérifiez l'intégrité du fichier ZIP
Avec la CLI, vérifiez si le drapeau --blueprint-may-read-adjacent-files est nécessaire
Assurez-vous de la présence de toutes les ressources nécessaires dans le paquet

Qu’est-ce qu’un paquet Blueprint ?​

Utiliser les paquets Blueprint​

Sur le site​

Dans la CLI​

Créer des paquets Blueprint​

Structure de base​

Exemple de Blueprint avec ressources groupées​

Créer un paquet ZIP​

Souplesse de la structure des fichiers ZIP​

Dépannage​