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 for sharing or CI

• Switch WP/PHP versions quickly to reproduce issues

• Debug plugin/theme code with Xdebug in isolation

Inputs required

• Node.js 20.18+ (node -v )

• Project path to mount

• Desired WP version/PHP version (optional)

• Blueprint location if using one

• Port preference (default 9400)

Procedure

1. Quick local spin-up

cd /path/to/your-plugin-or-theme npx @wp-playground/cli@latest server --auto-mount

Opens on http://localhost:9400. Auto-detects and installs plugin/theme.

Common options:

Specify WP version

npx @wp-playground/cli@latest server --auto-mount --wp=6.9

Specify PHP version

npx @wp-playground/cli@latest server --auto-mount --php=8.2

Change port

npx @wp-playground/cli@latest server --auto-mount --port=9500

2. Manual mounts

For complex setups:

npx @wp-playground/cli@latest server
--mount=/path/to/plugin:/wordpress/wp-content/plugins/my-plugin
--mount=/path/to/theme:/wordpress/wp-content/themes/my-theme

3. Run a Blueprint

Blueprints define site setup in JSON:

Run from local file

npx @wp-playground/cli@latest run-blueprint --blueprint=./my-blueprint.json

Run from URL

npx @wp-playground/cli@latest run-blueprint --blueprint=https://example.com/blueprint.json

Example blueprint.json:

{ "landingPage": "/wp-admin/", "preferredVersions": { "php": "8.2", "wp": "6.9" }, "steps": [ { "step": "login", "username": "admin", "password": "password" }, { "step": "installPlugin", "pluginZipFile": { "resource": "url", "url": "https://downloads.wordpress.org/plugin/query-monitor.zip" } }, { "step": "activatePlugin", "pluginPath": "query-monitor/query-monitor.php" } ] }

4. Build a snapshot

Create shareable ZIP:

npx @wp-playground/cli@latest build-snapshot
--blueprint=./setup.json
--outfile=./my-site.zip

5. Debug with Xdebug

npx @wp-playground/cli@latest server --auto-mount --xdebug

Connect your IDE (VS Code/PhpStorm) to the port shown in output.

6. Browser-only workflows

No CLI needed:

• Quick preview: https://playground.wordpress.net/

• With blueprint: https://playground.wordpress.net/?blueprint-url=YOUR_JSON_URL

• Blueprint editor: Use the live editor at playground.wordpress.net

7. Version testing matrix

Test across versions:

Test on WP 6.8

npx @wp-playground/cli@latest server --auto-mount --wp=6.8

Test on WP 6.9

npx @wp-playground/cli@latest server --auto-mount --wp=6.9

Test on PHP 8.1

npx @wp-playground/cli@latest server --auto-mount --php=8.1

Verification

• Plugin/theme appears in admin and is active

• For blueprints: re-run with --verbosity=debug to confirm steps executed

• Test the specific functionality you're debugging

Failure modes / debugging

CLI exits complaining about Node:

• Upgrade to Node.js 20.18+

Mount not applied:

• Use absolute paths

• Add --verbosity=debug

Blueprint cannot read local assets:

• Add --blueprint-may-read-adjacent-files

Port already used:

• Change with --port=9500

Slow/locked UI:

• Try disabling or enabling --experimental-multi-worker

Limitations

Playground uses WebAssembly + SQLite, so:

• No MySQL (uses SQLite)

• Some PHP extensions may not work

• Not suitable for production data

Escalation

If PHP extensions or native DB access are required:

• Fall back to wp-env, Docker, or Local

Consult:

• WordPress Playground Docs

• Playground GitHub