Wp Playground

1---
2name: wp-playground
3description: "Use for WordPress Playground workflows: fast disposable WP instances in the browser or locally via @wp-playground/cli (server, run-blueprint, build-snapshot), auto-mounting plugins/themes, switching WP/PHP versions, blueprints, and debugging (Xdebug)."
4compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Playground CLI requires Node.js 20.18+; runs WP in WebAssembly with SQLite."
5---
6 
7# WordPress Playground
8 
9## When to use
10 
11- Spin up a disposable WordPress to test a plugin/theme without full stack setup.
12- Run or iterate on Playground Blueprints (JSON) locally.
13- Build a reproducible snapshot of a site for sharing or CI.
14- Switch WP/PHP versions quickly to reproduce issues.
15- Debug plugin/theme code with Xdebug in an isolated Playground.
16 
17## Inputs required
18 
19- Host machine readiness: Node.js ≥ 20.18, `npm`/`npx` available.
20- Project path to mount (`--auto-mount` or explicit mount mapping).
21- Desired WP version/PHP version (optional; defaults to latest WP, PHP 8.3).
22- Blueprint location/URL if running a blueprint.
23- Port preference if 9400 conflicts.
24- Whether Xdebug is needed.
25 
26## Procedure
27 
28### 0) Guardrails
29 
30- Playground instances are ephemeral and SQLite-backed; **never** point at production data.
31- Confirm Node ≥ 20.18 (`node -v`) before running CLI.
32- If mounting local code, ensure it is clean of secrets; Playground copies files into an in-memory FS.
33 
34### 1) Quick local spin-up (auto-mount)
35 
36```bash
37cd <plugin-or-theme-root>
38npx @wp-playground/cli@latest server --auto-mount
39```
40- Opens on http://localhost:9400 by default. Auto-detects plugin/theme and installs it.
41- Add `--wp=<version>` / `--php=<version>` as needed.
42- For classic full installs already present, add `--skip-wordpress-setup` and mount the whole tree.
43 
44### 2) Manual mounts or multiple mounts
45 
46- Use `--mount=/host/path:/vfs/path` (repeatable) when auto-mount is insufficient (multi-plugin, mu-plugins, custom content).
47- Mount before install with `--mount-before-install` for bootstrapping installer flows.
48- Reference: `references/cli-commands.md`
49 
50### 3) Run a Blueprint (no server needed)
51 
52```bash
53npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url>
54```
55- Use for scripted setup/CI validation. Supports remote URLs and local files.
56- Allow bundled assets in local blueprints with `--blueprint-may-read-adjacent-files` when required.
57- See `references/blueprints.md` for structure and common flags.
58 
59### 4) Build a snapshot for sharing
60 
61```bash
62npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site.zip
63```
64- Produces a ZIP you can load in Playground or attach to bug reports.
65 
66### 5) Debugging with Xdebug
67 
68- 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.
69- Combine with `--auto-mount` for plugin/theme debugging.
70- Checklist: `references/debugging.md`
71 
72### 6) Version switching
73 
74- Use `--wp=` to pin WP (e.g., 6.9.0) and `--php=` to test compatibility.
75- If feature depends on Gutenberg trunk, prefer the latest WP release plus plugin if available; Playground images track stable WP plus bundled Gutenberg.
76 
77### 7) Browser-only workflows (no CLI)
78 
79- Launch quick previews with URL fragments or query params:
80  - Fragment: `https://playground.wordpress.net/#<base64-or-json-blueprint>`
81  - Query: `https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>`
82- Use the live Blueprint Editor (playground.wordpress.net) to author blueprints with schema help; paste JSON and copy a shareable link.
83 
84## Verification
85 
86- Verify mounted code is active (plugin listed/active; theme selected).
87- For blueprints/snapshots, re-run with `--verbosity=debug` to confirm steps executed.
88- Run targeted smoke (e.g., `wp plugin list` inside Playground shell via browser terminal if exposed) or UI click-path.
89 
90## Failure modes / debugging
91 
92- **CLI exits complaining about Node**: upgrade to ≥ 20.18.
93- **Mount not applied**: check path, use absolute path, add `--verbosity=debug`.
94- **Blueprint cannot read local assets**: add `--blueprint-may-read-adjacent-files`.
95- **Port already used**: `--port=<free-port>`.
96- **Slow/locked UI**: disable `--experimental-multi-worker` if enabled; or enable it to improve throughput on CPU-bound runs.
97 
98## Escalation
99 
100- If PHP extensions or native DB access are required, Playground may be unsuitable; fall back to full WP stack or wp-env/Docker.
101- For browser-only embedding or VS Code extension specifics, consult the upstream docs: https://wordpress.github.io/wordpress-playground/
102