The playground team has been working on a brand-new interface for WordPress Playground, and we would love your help testing it before it officially launches. Whether you are using a laptop or a mobile phone, we want to know how the new UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. feels, responds to, and works with your clicks and taps.

You do not have to test everything. Pick one or two modules below, explore them, and tell us what worked well or what could be improved.

🔗 Test environment: Open the new Playground UI

What We Are Looking For

While testing, please pay attention to:

• Clear text: Are buttons, labels, descriptions, and instructions easy to understand?
• Logical mechanics: Do workflows behave as you expect? Is it clear what each action will do?
• Design issues: Do you see overlapping text, clipped content, missing controls, or broken layouts?
• Helpful feedback: What feature or small change would make the experience smoother?

Testing on Desktop and Mobile

If possible, try the UI in both a desktop browser and a mobile browser.

On mobile:

• Swipe the bottom toolbar horizontally to find tools that are not currently visible, such as Files, Logs, or Export.
• Tool panels open over the site. Use the X button to close a panel.
• In the Files panel, tap Browse files to open the file tree.
• Use the file upload control instead of drag and drop.

Please do not upload private files, passwords, APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. keys, or other sensitive information while testing.

Choose Your Testing Adventure

Module 1: Create and Manage Playgrounds

A good starting point for a five-minute test.

1. Open the test environment and wait for the initial Playground to finish loading. A Playground is created automatically when the page opens.
2. Select New in the bottom toolbar.
3. In the Blueprint gallery, select Vanilla WordPress. Selecting the card immediately creates a fresh Playground.
4. Open Site details. Change the WordPress version or PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php version, then select Create a fresh Playground. Verify that the new Playground uses the selected versions.
5. In Site details, select Rename Playground and give it a recognizable name. You can also rename it from Playgrounds → Actions (⋮) → Rename.
6. Open Playgrounds, open the current Playground’s Actions (⋮) menu, and select Save in browser storage. Confirm that its status changes from an autosave to a permanently saved Playground.
7. Refresh the browser. Open Playgrounds, find the site under Saved, and open it again. Saved Playgrounds and Recent autosaves are listed separately.
8. Open the saved Playground’s Actions (⋮) menu, select Delete, and confirm the deletion.

Note: Autosaves are periodic snapshots and may not include every recent change. Use Save in browser storage when you want to keep a Playground.

What to look out for:

• Did the initial and fresh Playgrounds load successfully?
• Was it clear that changing a version creates a fresh Playground?
• Were rename, save, restore, and delete actions easy to find?
• After refreshing, was the difference between Recent autosaves and
  Saved clear?
• Could you reach every action comfortably on mobile?

Module 2: The Blueprint Experience

Test the different ways to start and inspect a custom setup.

1. Select New → Blueprint gallery.
2. Search or browse the gallery and read the descriptions shown on the cards.
3. Select a Blueprint card. The card launches a fresh Playground immediately, so there is no separate details screen.
4. After it loads, open Blueprint in the bottom toolbar to inspect its blueprint.json file.
5. Select New → Blueprint URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org, enter a publicly accessible Blueprint URL, and select Create Playground.
6. Select New → Write a Blueprint, edit the example JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML., and select Create Playground.
7. To keep the resulting site, use Playgrounds → Actions (⋮) → Save in browser storage. To download the Blueprint itself, open Blueprint and select Export.

Be careful: In an editable autosaved Playground, Run Blueprint and reset site recreates the Playground and replaces its files. In a permanently saved Playground, the Blueprint editor is read-only.

What to look out for:

• Was the gallery easy to browse and search?
• Was it clear that selecting a card would immediately create a Playground?
• Did the Blueprint URL and raw JSON workflows show useful validation and error messages?
• Was the difference between saving a Playground and exporting a Blueprint clear?
• Did the selected Blueprint finish without crashing?

Module 3: Files, Database, and Logs

Test the developer tools.

1. Launch a Playground and open Files.
2. On mobile, select Browse files to reveal the file tree.
3. Try Create new folder and Create new file. Enter a name, confirm it, and verify that the item remains visible after you select something else.
4. Open a harmless file such as readme.html, or use the test file you just created. Add a short comment, select Save file, reopen the file, and confirm that the change remains. Avoid editing wp-config.php for this test.
5. Use Upload files to upload a small, non-sensitive test file. On desktop, you may also try dragging a test file into the file manager and report whether that works.
6. Open Database. Select Open Adminer or Open phpMyAdmin, then browse a table without changing its data. If the viewer cannot install or reports a download/fetch error, include the exact error in your feedback.
7. Open Logs. Confirm that you see either a clear Nothing logged yet state or relevant PHP, WordPress, and Playground messages. If you are comfortable doing so, trigger a harmless warning in a test file and check whether it appears.

What to look out for:

• Did newly created files and folders persist after focus moved elsewhere?
• Was the editor comfortable to use with a mobile keyboard?
• Were save and upload results clearly communicated?
• Did Adminer or phpMyAdmin open successfully? Were installation errors useful?
• Did the Logs panel clearly explain an empty state and distinguish message types?

Module 4: Import, Export, and Sharing

Test how Playground data moves between environments.

1. In an active Playground, open Export.
2. Under Download a copy, select Download as .zip. The ZIP should contain the current files, database, and edits.
3. Select New → Import zip → Choose a .zip file… and import the ZIP you just downloaded.
4. After the imported Playground loads, check that its pages, settings, files, and content were restored.
5. Open Export and select Copy link. Paste the result somewhere safe and verify that it is a usable URL. Important: This link recreates the original Blueprint setup only. It does not include later edits to files or content.
6. Optionally, test Export to GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ using a disposable repository you can modify safely. Connect your GitHub account and try exporting a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party., theme, or wp-content directory. The GitHub connection is not retained after a browser refresh.

👀 What to look out for:

• Did ZIP creation finish in a reasonable time?
• Did importing the ZIP restore the current site accurately?
• Did the UI clearly explain what the copied link includes and excludes?
• Were clipboard permission errors understandable?
• Was the scope of the GitHub export clear before anything was pushed?
• Were success, progress, and error messages helpful?

How to Share Your Feedback

Found a bug or have an idea for a better workflow? Please include:

• Your device, operating system, and browser.
• The module and step you tested.
• The steps needed to reproduce the problem.
• What you expected to happen and what actually happened.
• Your thoughts on text clarity, mechanics, and visual design.
• Screenshots or short screen recordings, when possible.

Remove private information, access tokens, repository secrets, and personal files from screenshots or recordings before posting them.

👉 Share feedback, bugs, and ideas in the official GitHub issue:

New Dock UI review — Issue #4092

You will need to sign in to GitHub to post a comment.

Thank you for helping us make WordPress Playground better for everyone. Happy testing! 🚀

@wp-now/wp-now is now deprecated and will not receive future updates. If you use wp-now for local WordPress development, the recommended replacement is @wp-playground/cli. The process took a few months because the Playground team was working to replace all the capabilities from wp-now.

This change is now reflected in the Playground documentation through PR #3767, which documents the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. path from wp-now to Playground CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. and updates the CLI docs to lead with the new start command for familiar wp-now-style workflows. server command still available for more complex workflows.

Why this change

wp-now helped make local WordPress development fast and portable by running WordPress with the Playground runtime, without Docker, MySQLMySQL MySQL is a relational database management system. A database is a structured collection of data where content, configuration and other options are stored. https://www.mysql.com, or ApacheApache Apache is the most widely used web server software. Developed and maintained by Apache Software Foundation. Apache is an Open Source software available for free.. Over the last few years, though, new local development work has moved toward the official Playground CLI.

With the recent implementation of start command, it means the remaining gap has closed: Playground CLI now supports the familiar wp-now behavior and adds more room for customization through the broader WordPress Playground toolchain.

What to use instead

For most local development workflows, use:

npx @wp-playground/cli@latest start

It automatically detects whether the current directory is a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party., theme, wp-content directory, or full WordPress installation. It also persists the site between runs, enables login, and opens the browser by default.

For lower-level control, use:

npx @wp-playground/cli@latest server

The server command is best when you want to define mounts, storage behavior, versions, Blueprints, or automation explicitly. It is also a better fit for CI and scripted development environments.

Migration guide

Most wp-now commands map directly to @wp-playground/cli start:

1. Replace the package name

If you currently run:

npx @wp-now/wp-now start

Run this instead:

npx @wp-playground/cli@latest start

You do not need to install the package globally. Using npx keeps your workflow on the latest Playground CLI release.

2. Run start from the project directory

The main workflow difference is how saved sites are associated with local paths.

With wp-now, --path=./plugin selected both the project and the saved site. With Playground CLI, start saves the site for the current working directory. For the closest match to wp-now --path, change into the project directory first:

cd ./plugin
npx @wp-playground/cli@latest start

start --path=./plugin still mounts that folder, but the saved site belongs to the directory where the command was run. If you want one persistent site per project, run the command from that project directory.

3. Keep version and Blueprint flags

Common version and Blueprint flags continue to work:

npx @wp-playground/cli@latest start --wp=6.8 --php=8.3
npx @wp-playground/cli@latest start --blueprint=./blueprint.json

Use --skip-browser if you do not want the browser to open automatically:

npx @wp-playground/cli@latest start --skip-browser

Use --reset to delete the stored site and start fresh:

npx @wp-playground/cli@latest start --reset

4. Understand persistence

When Playground CLI creates WordPress for you, start stores the site in:

~/.wordpress-playground/sites/<path-hash>/

The <path-hash> is derived from the command’s current working directory. This keeps projects isolated from one another while preserving the site between CLI runs.

If you run Playground CLI on a full WordPress directory, or mount a directory at /wordpress, that directory becomes the WordPress site and changes are written there instead.

What this means for existing wp-now users

Existing wp-now workflows should move to Playground CLI. The migration is intentionally small for common use cases: replace the package, use start, and run it from the project directory you want to persist.

For more advanced workflows, Playground CLI offers a larger surface area than wp-now, including server, run-blueprint, build-snapshot, custom mounts, and deeper configuration options.

See the updated documentation:

• wp-now migration page
• Playground CLI documentation
• PR #3767: Document wp-now migration to Playground CLI

Reviewing a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. or theme Pull Request has always carried a bit of friction. To actually test the change, someone had to pull the branch, spin up a local WordPress, and activate the code by hand. That is exactly why the WordPress Playground PR Preview GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ Action exists: it adds a “Preview in WordPress Playground” button straight to the PR. As a result, any reviewer opens the environment with the code already applied in the browser, without installing anything.

The action already existed in v2. However, version 3 underwent an important simplification: the manual “glue” that each project had to write for builds was replaced by ready-made, reusable workflows. In this post, therefore, I’ll cover what the action does, why it’s worth it, how to set it up in the two possible scenarios, practical examples, and the step-by-step path to migrate from v2.

What the WordPress Playground PR Preview action does

In short, it publishes a preview link on the Pull Request. That link points to a WordPress Playground instance, in other words, a full WordPress running through WebAssembly (WASM) in the browser of whoever clicks it. Playground boots clean, installs the plugin or theme from the PR branch, and automatically activates everything.

The result, then, is a disposable, isolated environment created on demand that mirrors the state of that branch exactly.

Why use it

• One-click testing: the reviewer needs no local setup and no WordPress installed.
• Works with forks: external contributions get a preview without exposing repository secrets.
• Plugin, theme, or both: you can create scenarios that combine several artifacts.
• Handles complex builds: projects that rely on Composer, npm, or Vite are supported too, through dedicated workflows.
• Real sandbox: the code runs in the user’s browser, isolated, without touching any server.

Scenario 1: no build step

This is the simplest path. Use it when the files committed to the repository run as-is, without compilation, for example, a plain PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php plugin.

First, create .github/workflows/pr-preview.yml:

name: PR Preview
on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  preview:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: WordPress/action-wp-playground-pr-preview@v3
        with:
          plugin-path: .
          github-token: ${{ secrets.GITHUB_TOKEN }}

For a theme, swap plugin-path: . for theme-path: .. Besides that, the permissions blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. is mandatory: the action needs pull-requests: write to write the link on the PR and contents: read to read the code.

Main inputs of the direct action

You provide one of plugin-path, theme-path, blueprint, or blueprint-url. The mode, in turn, decides whether the link goes into the PR description body or as a comment.

Scenario 2: with a build step

When the preview depends on compilation (npm run build, Composer, etc.), v3 uses two workflows that talk to each other. First, one builds the untrusted PR code with read-only permissions. Then, the other publishes the result from the default branch, with write permissions, without ever executing the PR code. The only point of contact between them is the generated ZIP file — and that is precisely what keeps the flow secure.

The build workflow lives in .github/workflows/pr-preview-build.yml:

name: PR Preview - Build
on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

jobs:
  build:
    uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-build.yml@v3
    with:
      artifacts: my-plugin=build/my-plugin.zip
      node-version: '20'
      build-command: |
        npm ci
        npm run build:plugin-zip

The publish workflow, in turn, lives in .github/workflows/pr-preview-publish.yml:

name: PR Preview - Publish
on:
  workflow_run:
    workflows: ["PR Preview - Build"]
    types: [completed]

permissions:
  contents: write
  pull-requests: write

jobs:
  publish:
    permissions:
      contents: write
      pull-requests: write
    uses: WordPress/action-wp-playground-pr-preview/.github/workflows/preview-publish.yml@v3
    with:
      kind: plugin

The artifacts field uses the name=path/to/file.zip format — one per line, if you have several. The kind in publish, meanwhile, tells whether the artifact is a plugin or a theme. Besides that, the reusable workflows take care of automatically creating a ci-artifacts prerelease to host the ZIPs publicly. After all, Playground needs to download the asset, so it can’t be in a draft release.

Build workflow inputs

Practical example: custom Blueprint

Sometimes you need more than “install and activate”. Say, a plugin from the PR running alongside WooCommerce and already logged in as admin. In that case, use a Blueprint. It’s a JSON recipe that describes the site’s initial state.

- uses: WordPress/action-wp-playground-pr-preview@v3
  with:
    blueprint: |
      {
        "$schema": "https://playground.wordpress.net/blueprint-schema.json",
        "preferredVersions": { "php": "8.3", "wp": "6.6" },
        "steps": [
          { "step": "installPlugin",
            "pluginData": {
              "resource": "git:directory",
              "url": "https://github.com/${{ github.repository }}.git",
              "ref": "${{ github.event.pull_request.head.ref }}",
              "path": "/"
            },
            "options": { "activate": true } },
          { "step": "installPlugin",
            "pluginData": { "resource": "wordpress.org/plugins", "slug": "woocommerce" },
            "options": { "activate": true } },
          { "step": "login", "username": "admin" }
        ]
      }
    github-token: ${{ secrets.GITHUB_TOKEN }}

This Blueprint pins PHP 8.3 and WordPress 6.6, installs the code from the PR branch, adds WooCommerce from the official repository, and hands over an already-logged-in environment. For build scenarios, moreover, you can reference the generated ZIPs inside the Blueprint using the {{ARTIFACT_URL:<name>}} placeholder. That way, v3 resolves the public artifact URL for you.

Migrating from v2 to v3

In practice, the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. varies with the complexity of your setup.

Simple plugins and themes (no build): here, almost nothing changes. Switch the action reference from @v2 to @v3 and keep the same inputs.

# works the same in v2 and v3
- uses: WordPress/action-wp-playground-pr-preview@v3
  with:
    plugin-path: .
    github-token: ${{ secrets.GITHUB_TOKEN }}

Projects with a build: this is where the real gain is. On v2 you needed a build workflow, plus manual parsing of the artifact name, plus an expose-artifact-on-public-url helper, plus manual Blueprint generation, and still the manual release publishing. v3, by contrast, replaces all of that with the two reusable workflows (preview-build.yml and preview-publish.yml) shown above. The step-by-step, therefore, looks like this:

1. Create pr-preview-build.yml with the build workflow template.
2. Create pr-preview-publish.yml with the publish workflow template.
3. Define the artifacts in the artifacts field (name=path format).
4. Set kind: plugin or kind: theme in publish — or, alternatively, use blueprint with {{ARTIFACT_URL:<name>}} placeholders for setups with multiple ZIPs.

Inputs such as artifact-name, artifact-filename, artifact-source-run-id, pr-number, and commit-sha, which existed only for the manual glue, are no longer needed in most cases.

Finally, watch out for the mandatory release cleanup: the change that breaks the most in practice is that draft releases no longer work. After all, Playground can’t download assets from a draft release without authentication. Therefore, if you have ci-artifacts releases in draft, convert them to prerelease or delete them.

Common gotchas

• 404 error when opening the preview: the release is probably set as a draft instead of a prerelease. Fix it on the repository’s Releases tab.
• Plugin doesn’t show up as installed: the ZIP must be extracted to a folder named after the slug. Make sure your build does that. For example:
  bash mkdir -p stage/my-plugin && rsync -a ./ stage/my-plugin/ && (cd stage && zip -r ../my-plugin.zip my-plugin)
• Build failing when comparing against the base: if you use git diff against the base branch, set fetch-depth: 0 in the build workflow. After all, the default checkout brings only the latest commit.
• Permission error: the permissions block is missing at the workflow or job level.

Conclusion

If you already used v2 for builds, migrating is worth it: you delete dozens of lines of manual glue and get tested, community-maintained workflows in their place. On the other hand, if you don’t use PR preview in your plugin or theme repository yet, the no-build scenario solves it with a few lines of YAML — and noticeably improves the experience for whoever reviews code in your project.

The full documentation lives at wordpress.github.io/action-wp-playground-pr-preview. For the more specific cases, also check the detailed migration guide.