wp-playground_skill

This skill lets you quickly spin disposable WordPress playgrounds, mount plugins/themes, switch WP/PHP versions, and debug with Xdebug.

JavaScript

159

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill automattic/agent-skills --skill wp-playground

SKILL.md4.5 KB

Overview

This skill provides command and workflow guidance for WordPress Playground: fast, disposable WordPress instances in the browser or locally via the @wp-playground/cli. It covers auto-mounting plugins/themes, running blueprints, building snapshots, switching WP/PHP versions, and Xdebug-based debugging. Use it to iterate on code, reproduce issues, and create shareable reproducible sites quickly.

How this skill works

The skill explains how to run the Playground CLI (server, run-blueprint, build-snapshot), pass mount mappings, and select WP/PHP versions. It details auto-mount behavior, blueprint execution, snapshot creation, and Xdebug integration. It also lists guardrails, verification steps, common failure modes, and recommended flags for reproducible runs.

When to use it

Quickly test a plugin or theme without installing a full stack locally
Iterate on a Playground Blueprint or run scripted site setups in CI
Create a reproducible snapshot (ZIP/blueprint) for sharing or bug reports
Reproduce compatibility issues by switching WP and PHP versions
Debug plugin/theme code with Xdebug in an isolated environment

Best practices

Ensure host has Node.js >= 20.18 and npm/npx available before running the CLI
Never point Playground at production data; instances are ephemeral and SQLite-backed
Use --auto-mount from the plugin/theme root for fastest iteration and detection
Use absolute paths with --mount and --mount-before-install for complex or multi-mount setups
Add --verbosity=debug when a mount, blueprint, or install step fails to get detailed diagnostics

Example use cases

Local iteration: cd into a plugin repo and run npx @wp-playground/cli@latest server --auto-mount to preview and test changes
CI validation: run npx @wp-playground/cli@latest run-blueprint --blueprint=<file-or-url> to execute scripted site builds
Bug reproduction: build a snapshot with build-snapshot and attach the ZIP to an issue for maintainers to reproduce
Compatibility testing: pin --wp=6.9.0 and --php=8.0 to validate behavior across versions
Remote share: author a blueprint in the live editor and share the playground URL or fragment for browser-only review

FAQ

Yes. Use --auto-mount from your project root or explicit --mount=/host/path:/vfs/path. Use --mount-before-install when mounts must exist before WordPress setup.

How do I debug with Xdebug?

Start the server with --xdebug (or --enable-xdebug) and connect your IDE to the host/port shown in the CLI output. Combine with --auto-mount to debug your plugin/theme code.

What if the CLI complains about Node?

Upgrade Node to at least 20.18 (check with node -v). The CLI requires a modern Node runtime to run correctly.

When should I not use Playground?

If you require native PHP extensions, external DB servers, or production data, use a full WP stack or Docker/wp-env instead; Playground is ephemeral and SQLite-backed.