wp-playground
Use for WordPress Playground workflows: fast disposable WP instances in browser or locally via @wp-playground/cli, auto-mounting plugins/themes, switching WP/PHP versions, blueprints, and debugging with Xdebug.
When & Why to Use This Skill
This Claude skill integrates WordPress Playground to provide instant, disposable WordPress environments running in WebAssembly. It enables developers to rapidly test plugins and themes, execute automated site setups via JSON blueprints, and debug code across multiple PHP and WordPress versions without the need for a traditional local stack or database configuration.
Use Cases
- Plugin and Theme Testing: Quickly spin up an isolated WordPress instance to verify new features or bug fixes without the overhead of Docker or local servers.
- Cross-Version Compatibility: Test how your code performs across different WordPress (e.g., 6.8 vs 6.9) and PHP (e.g., 8.1 vs 8.2) versions with simple CLI flags.
- Automated Prototyping with Blueprints: Use JSON-based blueprints to automate complex site setups, including plugin installations and configuration steps, for demos or CI/CD.
- Isolated Debugging: Connect your IDE to a disposable environment via Xdebug to troubleshoot code in a clean, reproducible state.
- Shareable Snapshots: Build and export site snapshots as ZIP files to share reproducible environments with team members or for bug reporting.
| name | wp-playground |
|---|---|
| description | "Use for WordPress Playground workflows: fast disposable WP instances in browser or locally via @wp-playground/cli, auto-mounting plugins/themes, switching WP/PHP versions, blueprints, and debugging with Xdebug." |
| compatibility | "Playground CLI requires Node.js 20.18+. Runs WP in WebAssembly with SQLite." |
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=debugto 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: