Wp Playground

WordPress Playground

When to use

• Spin up a disposable WordPress to test a plugin/theme without full stack setup.
• Run or iterate on Playground Blueprints (JSON) locally.
• Build a reproducible snapshot of a site for sharing or CI.
• Switch WP/PHP versions quickly to reproduce issues.
• Debug plugin/theme code with Xdebug in an isolated Playground.

Inputs required

• Host machine readiness: Node.js ≥ 20.18, npm/npx available.
• Project path to mount (--auto-mount or explicit mount mapping).
• Desired WP version/PHP version (optional; defaults to latest WP, PHP 8.3).
• Blueprint location/URL if running a blueprint.
• Port preference if 9400 conflicts.
• Whether Xdebug is needed.

Procedure

0) Guardrails

• Playground instances are ephemeral and SQLite-backed; never point at production data.
• Confirm Node ≥ 20.18 (node -v) before running CLI.
• If mounting local code, ensure it is clean of secrets; Playground copies files into an in-memory FS.

1) Quick local spin-up (auto-mount)

cd <plugin-or-theme-root>
npx @wp-playground/cli@latest server --auto-mount

• Opens on http://localhost:9400 by default. Auto-detects plugin/theme and installs it.
• Add --wp=<version> / --php=<version> as needed.
• For classic full installs already present, add --skip-wordpress-setup and mount the whole tree.

2) Manual mounts or multiple mounts

• Use --mount=/host/path:/vfs/path (repeatable) when auto-mount is insufficient (multi-plugin, mu-plugins, custom content).
• Mount before install with --mount-before-install for bootstrapping installer flows.
• Reference: references/cli-commands.md

3) Run a Blueprint (no server needed)

npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>

• Use for scripted setup/CI validation. Supports remote URLs and local files.
• Allow bundled assets in local blueprints with --blueprint-may-read-adjacent-files when required.
• See references/blueprints.md for structure and common flags.

4) Build a snapshot for sharing

npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip

• Produces a ZIP you can load in Playground or attach to bug reports.

5) Debugging with Xdebug

• Start with --xdebug (or --enable-xdebug depending on CLI release) to expose an IDE key, then connect VS Code/PhpStorm to the host/port shown in CLI output.
• Combine with --auto-mount for plugin/theme debugging.
• Checklist: references/debugging.md

6) Version switching

• Use --wp= to pin WP (e.g., 6.9.0) and --php= to test compatibility.
• If feature depends on Gutenberg trunk, prefer the latest WP release plus plugin if available; Playground images track stable WP plus bundled Gutenberg.

7) Browser-only workflows (no CLI)

• Launch quick previews with URL fragments or query params:
• Fragment: https://playground.wordpress.net/#<base64-or-json-blueprint>
• Query: https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>
• Use the live Blueprint Editor (playground.wordpress.net) to author blueprints with schema help; paste JSON and copy a shareable link.

Verification

• Verify mounted code is active (plugin listed/active; theme selected).
• For blueprints/snapshots, re-run with --verbosity=debug to confirm steps executed.
• Run targeted smoke (e.g., wp plugin list inside Playground shell via browser terminal if exposed) or UI click-path.

Failure modes / debugging

• CLI exits complaining about Node: upgrade to ≥ 20.18.
• Mount not applied: check path, use absolute path, add --verbosity=debug.
• Blueprint cannot read local assets: add --blueprint-may-read-adjacent-files.
• Port already used: --port=<free-port>.
• Slow/locked UI: disable --experimental-multi-worker if enabled; or enable it to improve throughput on CPU-bound runs.

Escalation

• If PHP extensions or native DB access are required, Playground may be unsuitable; fall back to full WP stack or wp-env/Docker.
• For browser-only embedding or VS Code extension specifics, consult the upstream docs: https://wordpress.github.io/wordpress-playground/

Blueprint quick reference

Blueprints are JSON recipes that describe how Playground should set up WordPress.

Minimal example

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "steps": [
    { "step": "installTheme", "themeZipUrl": "https://downloads.wordpress.org/theme/twentytwentythree.zip" },
    { "step": "installPlugin", "pluginZipUrl": "https://downloads.wordpress.org/plugin/classic-editor.zip" }
  ]
}

Common steps (non-exhaustive)

• setSiteUrl, setHomeUrl
• installTheme, installPlugin (ZIP URLs or local paths when allowed)
• activateTheme, activatePlugin
• runPHP (inline PHP)
• applyPatches (filesystem patch)
• writeFile (create/update files)
• importFile (XML/WXR)
• wpConfigConstants (define constants)
• preferredVersions (pick WP/PHP; matches CLI --wp / --php)
• blueprintSteps that include extraLibraries (e.g., Jetpack) and features.networking when browser networking is required

Tips

• Use --blueprint-may-read-adjacent-files when the blueprint needs local files (e.g., custom plugin ZIP) during run-blueprint or build-snapshot.
• For iterative authoring, keep blueprints small and compose via separate files.
• Validate against the published schema URL above to catch typos.
• For Gutenberg/nightly testing, set --wp=<version> to align with target WP.
• To share quickly, encode the blueprint as base64 in the Playground URL fragment or host the JSON/ZIP and pass ?blueprint-url=….

Playground CLI command cheatsheet

Requires Node.js 20.18+ and npm/npx.

Latest version: 3.0.20 (November 2025)

What's new in 2025

• PHP 8.3 is now the default (since July 2025).
• New PHP extensions: ImageMagick, SOAP, and AVIF GD support.
• OpCache enabled: 42% faster response times (185ms → 108ms average).
• Multi-worker default: --experimental-multi-worker now defaults to CPU count minus one.

Install / run server

• npx @wp-playground/cli@latest server [--port=9400] [--auto-mount] [--wp=<ver>] [--php=<ver>] [--verbosity=debug] [--blueprint=<url-or-path>]
• Mounts:
• --auto-mount (detect plugin/theme in CWD)
• --mount=/abs/host:/vfs/path (repeatable)
• --mount-before-install (apply mounts before WP install)

Run a blueprint

• npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url> [--blueprint-may-read-adjacent-files] [--wp=<ver>] [--php=<ver>] [--verbosity=debug]
• Use for scripted setup; no persistent server.

Build a snapshot

• npx @wp-playground/cli@latest build-snapshot --blueprint=<file-or-url> --outfile=./site.zip [--verbosity=debug]
• Produces a sharable ZIP usable by Playground UI or other CLI commands.

Debugging flags

• --xdebug / --enable-xdebug (depends on release) to start Xdebug listener.
• --experimental-multi-worker to speed multi-step blueprints; disable if unstable.

Version control

• --wp=<version> to pick WordPress version (defaults to latest).
• --php=<version> to pick PHP version (defaults to 8.3 since July 2025).

Debugging WordPress Playground

• Start CLI with Xdebug: server --auto-mount --xdebug (or --enable-xdebug depending on release). The CLI prints host/port and IDE key to configure your debugger.
• If breakpoints are not hit, confirm:
• IDE listens on the port shown by CLI.
• Path mappings include the mounted VFS path used by Playground.
• For slow or stuck runs:
• Add --verbosity=debug to see step-level logs.
• Disable --experimental-multi-worker if it was enabled.
• For mount issues:
• Prefer absolute paths in --mount.
• Use --mount-before-install when installer steps need files present early.
• To inspect runtime state:
• Open the Playground browser console; the Service Worker logs network/FS events.
• Use the “Terminal” tab (if available) to run WP-CLI inside the instance.