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