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