Blueprint

WordPress Playground Blueprints

Overview

A Blueprint is a JSON file that declaratively configures a WordPress Playground instance — installing plugins/themes, setting options, running PHP/SQL, manipulating files, and more.

Core principle: Blueprints are trusted JSON-only declarations. No arbitrary JavaScript. They work on web, Node.js, and CLI.

Quick Start Template

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [{ "step": "login" }]
}

Top-Level Properties

All optional. Only documented keys are allowed — the schema rejects unknown properties.

preferredVersions Values

• php: Major.minor only: "7.4", "8.0", "8.1", "8.2", "8.3", "8.4", "8.5", or "latest". Patch versions like "7.4.1" are invalid. Check the schema for currently supported versions.
• wp: Recent major versions, "latest", "beta", "nightly"/"trunk", or a URL to a custom zip. The schema also accepts false for PHP-only Playground; do not combine wp: false with WordPress-only fields such as plugins, siteOptions, login, or WordPress-only steps.

Shorthands vs Steps

Shorthands (login, plugins, siteOptions, constants) are expanded and prepended to steps in an unspecified order. Use explicit steps when execution order matters.

Resource References

Resources tell Playground where to find files. Used by installPlugin, installTheme, writeFile, writeFiles, importWxr, etc.

git:directory — Installing from GitHub

{
  "resource": "git:directory",
  "url": "https://github.com/WordPress/gutenberg",
  "ref": "trunk",
  "refType": "branch",
  "path": "/"
}

• When using a branch or tag name for ref, you must set refType ("branch" | "tag" | "commit" | "refname"). Without it, only "HEAD" resolves reliably.
• path selects a subdirectory (defaults to repo root).

literal:directory — Inline File Trees

{
  "resource": "literal:directory",
  "name": "my-plugin",
  "files": {
    "plugin.php": "<?php /* Plugin Name: My Plugin */ ?>",
    "includes": {
      "helper.php": "<?php // helper code ?>"
    }
  }
}

• files uses nested objects for subdirectories — keys are filenames or directory names, values are plain strings (file content) or objects (subdirectories). Never use resource references as values.
• Do NOT use path separators in keys (e.g. "includes/helper.php" is wrong — use a nested "includes": { "helper.php": "..." } object).

Steps Reference

Every step requires "step": "<name>". Any step can optionally include "progress": { "weight": 1, "caption": "Installing..." } for UI feedback.

Plugin & Theme Installation

{
  "step": "installPlugin",
  "pluginData": { "resource": "wordpress.org/plugins", "slug": "gutenberg" },
  "options": { "activate": true, "targetFolderName": "gutenberg" },
  "ifAlreadyInstalled": "overwrite"
}

{
  "step": "installTheme",
  "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfour" },
  "options": { "activate": true, "importStarterContent": true },
  "ifAlreadyInstalled": "overwrite"
}

• Use pluginData / themeData — NOT the deprecated pluginZipFile / themeZipFile.
• pluginData / themeData accept any FileReference or DirectoryReference — a zip URL, a wordpress.org/plugins slug, a git:directory, or a literal:directory (no zip wrapper needed).
• options.activate controls activation. No need for a separate activatePlugin/activateTheme step when using installPlugin/installTheme.
• ifAlreadyInstalled: "overwrite" | "skip" | "error"

Activation (standalone)

Only needed for plugins/themes already on disk (e.g. after writeFile/writeFiles):

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

{ "step": "activateTheme", "themeFolderName": "twentytwentyfour" }

File Operations

{ "step": "writeFile", "path": "/wordpress/wp-content/mu-plugins/custom.php", "data": "<?php // code" }

data accepts a plain string (as shown above) or a resource reference (e.g. { "resource": "url", "url": "https://..." }).

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/",
      "includes": {
        "helpers.php": "<?php // helpers"
      }
    }
  }
}

`writeFiles` requires a DirectoryReference (literal:directory or git:directory) as filesTree — not a plain object.

Other file operations: mkdir, cp, mv, rm, rmdir, unzip.

Running Code

runPHP:

{ "step": "runPHP", "code": "<?php require '/wordpress/wp-load.php'; update_option('key', 'value');" }

GOTCHA: You must require '/wordpress/wp-load.php'; to use any WordPress functions.

wp-cli:

{ "step": "wp-cli", "command": "wp post create --post_type=page --post_title='Hello' --post_status=publish" }

The step name is wp-cli (with hyphen), NOT cli or wpcli.

runSql:

{ "step": "runSql", "sql": { "resource": "literal", "name": "q.sql", "contents": "UPDATE wp_options SET option_value='val' WHERE option_name='key';" } }

Site Configuration

{ "step": "setSiteOptions", "options": { "blogname": "My Site", "blogdescription": "A tagline" } }

{ "step": "defineWpConfigConsts", "consts": { "WP_DEBUG": true } }

{ "step": "setSiteLanguage", "language": "en_US" }

{ "step": "defineSiteUrl", "siteUrl": "https://example.com" }