WordPress

Taking Playground Further: Meet Blueprints!

El Puas 03/10/2025

What is WordPress Playground?

WordPress Playground lets you run a fully functional WordPress site directly in your browser — no setup needed. It’s a great tool for quick testing, development, and learning WordPress without hassle. If you’re new to Playground, you might want to check my previous blog post for an easy-to-follow overview: Read my introduction to WordPress Playground here! (opens in a new tab).

What Exactly Are Blueprints?

Blueprints are powerful JSON files that tell Playground exactly how to set up your WordPress environment. With Blueprints, you can quickly create and share customized WordPress setups, perfect for:

Let’s check how Blueprints work and how you can use them!

A blueprint is a JSON file that specifies which plugins, themes, and settings to load automatically. It is a recipe for creating your WordPress Playground environment.

Why use Blueprints? Instead of manually installing plugins or configuring settings every time, you load your Blueprint, and your ideal environment appears instantly.

Simple Example of a Blueprint

Here’s how a basic Blueprint looks:

{
  "preferredVersions": {
    "wp": "6.5",
    "php": "7.4"
  },
  "steps": [
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "wordpress.org/plugins",
        "slug": "coblocks"
      }
    }
  ]
}

This simple Blueprint specifies that we want WordPress version 6.5 and PHP 7.4, and it automatically installs the CoBlocks plugin (from the WordPress.org plugin directory) when the Playground starts.

How do you use a Blueprint? Just add it to the Playground URL as a fragment. For example:

<https://playground.wordpress.net/#{"preferredVersions":{"wp":"6.5","php":"7.4"}>}

Paste your JSON after the # as shown above (make sure it’s all one line). You can also upload the Blueprint JSON file directly in the Playground interface via the “Load Blueprint” option.

Next Step: Let’s Add a Theme!

Now that we’ve covered the basics, let’s take it a step further. In the next example, we’ll modify the Blueprint to install a theme and configure the site automatically.

{
  "steps": [
    {
      "step": "installTheme",
      "themeData": {
        "resource": "wordpress.org/themes",
        "slug": "twentytwentyfour"
      }
    },
    {
      "step": "activateTheme",
      "themeFolderName": "twentytwentyfour"
    }
  ]
}

What this does:

By adding two steps – one to install the theme and another to activate it – our Playground will come up with Twenty Twenty-Four already set as the active theme.

Advanced Blueprint: Plugins, Custom Content, and Settings

You already know the basics, so let’s get more interesting. One powerful Playground feature is the ability to automatically insert custom content (posts, pages, settings, etc.) every time you spin up a new instance.

Here’s an advanced but practical example. This full Blueprint will do the following:

{
  "landingPage": "/wp-admin/edit.php",
  "login": true,
  "steps": [
    {
      "step": "setSiteOptions",
      "options": {
        "blogname": "My Awesome Playground",
        "blogdescription": "Testing WordPress Playground Blueprints!"
      }
    },
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "wordpress.org/plugins",
        "slug": "coblocks"
      }
    },
    {
      "step": "installTheme",
      "themeData": {
        "resource": "wordpress.org/themes",
        "slug": "twentytwentyfour"
      }
    },
    {
      "step": "activateTheme",
      "themeFolderName": "twentytwentyfour"
    },
    {
      "step": "runPHP",
      "code": "<?php require_once 'wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'Hello from Playground!', 'post_content' => '<!-- wp:paragraph --><p>This is my first blog post using Playground!</p><!-- /wp:paragraph -->', 'post_status' => 'publish', 'post_author' => 1)); ?>"
    },
    {
      "step": "runPHP",
      "code": "<?php require_once 'wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'About Playground', 'post_content' => '<!-- wp:paragraph --><p>Playground is awesome!</p><!-- /wp:paragraph -->', 'post_status' => 'publish', 'post_type' => 'page', 'post_author' => 1)); ?>"
    }
  ]
}

Important Notes:

Creating Your URL: Base64 Encoding (Recommended)

For more complex Blueprints (like the one above), WordPress Playground officially recommends using Base64 encoding for the URL. This prevents issues where spaces, quotes, or special characters in the JSON might break your URL.

How to encode your JSON Blueprint:

  1. Copy your Blueprint JSON into a text encoder (you can use an online tool or a command-line tool) and convert it to a Base64 string.

  2. Take that Base64 string and append it to the Playground URL after the #. For example:

<https://playground.wordpress.net/#YOUR_BASE64_ENCODED_STRING>

Here’s an example of an encoded Blueprint URL (already Base64 encoded) for the full Blueprint above. Clicking this URL will instantly launch Playground with the exact setup we defined (custom site title, theme, plugin, and content all loaded):

<https://playground.wordpress.net/#ewogICJsYW5kaW5nUGFnZSI6ICIvd3AtYWRtaW4vZWRpdC5waHAiLAogICJsb2dpbiI6IHRydWUsCiAgInN0ZXBzIjogW3sic3RlcCI6ICJzZXRTaXRlT3B0aW9ucyIsICJvcHRpb25zIjogeyJibG9nbmFtZSI6ICJNeSBBd2Vzb21lIFBsYXlncm91bmQiLCAiYmxvZ2Rlc2NyaXB0aW9uIjogIlRlc3RpbmcgV29yZFByZXNzIFBsYXlncm91bmQgQmx1ZXByaW50cyEifX0sIHsic3RlcCI6ICJpbnN0YWxsUGx1Z2luIiwgInBsdWdpbkRhdGEiOiB7ICJyZXNvdXJjZSI6ICJ3b3JkcHJlc3Mub3JnL3BsdWdpbnMiLCAic2x1ZyI6ICJjb2Jsb2NrcyIgfX0sIHsic3RlcCI6ICJpbnN0YWxsVGhlbWUiLCAidGhlbWVEYXRhIjogeyAicmVzb3VyY2UiOiAid29yZHByZXNzLm9yZy90aGVtZXMiLCAic2x1ZyI6ICJ0d2VudHl0d2VudHlmb3VyIiB9fSwgeyJzdGVwIjogImFjdGl2YXRlVGhlbWUiLCAidGhlbWVGb2xkZXJOYW1lIjogInR3ZW50eXR3ZW50eWZvdXIifSwgeyJzdGVwIjogInJ1blBIUCIsICJjb2RlIjogIjw/cGhwIHJlcXVpcmVfb25jZSAnd29yZHByZXNzL3dwLWxvYWQucGhwJzsgd3BfaW5zZXJ0X3Bvc3QoYXJyYXkoJ3Bvc3RfdGl0bGUnID0+ICdIZWxsbyBmcm9tIFBsYXlncm91bmQhJywgJ3Bvc3RfY29udGVudCcgID0+ICc8IS0tIHdwOnBhcmFncmFwaCAtLT48cD5UaGlzIGlzIG15IGZpcnN0IGJsb2cgcG9zdCB1c2luZyBQbGF5Z3JvdW5kITwvcD48IS0tIC93cDpwYXJhZ3JhcGggLS0+JywgJ3Bvc3Rfc3RhdHVzJyA9PiAncHVibGlzaCcsICdwb3N0X2F1dGhvcicgPT4gMSkpOyA/PiJ9LCB7InN0ZXAiOiAicnVuUEhQIiwgImNvZGUiOiAiPD9waHAgcmVxdWlyZV9vbmNlICd3b3JkcHJlc3Mvd3AtbG9hZC5waHAnOyB3cF9pbnNlcnRfcG9zdChhcnJheSgncG9zdF90aXRsZScgPT4gJ0Fib3V0IFBsYXlncm91bmQnLCAncG9zdF9jb250ZW50JyAgPT4gJzwhLS0gd3A6cGFyYWdyYXBoIC0tPjxwPlBsYXlncm91bmQgaXMgYXdlc29tZSE8L3A+PCEtLSAtL3dwOnBhcmFncmFwaCAtLT4nLCAncG9zdF9zdGF0dXMnID0+ICdwdWJsaXNoJywgJ3Bvc3RfdHlwZScgPT4gJ3BhZ2UnLCAncG9zdF9hdXRob3InID0+IDEpKTsgPz4ifV19>

Why Base64? It’s recommended because:

Installing Plugins from GitHub in Playground

Now that we understand the basics of Blueprints, let’s explore how you can install and activate a plugin directly from a GitHub repository inside WordPress Playground.

Why load plugins from GitHub? While WordPress.org is the standard place for plugins, sometimes you need to:

With Playground’s GitHub Proxy, you can install any plugin from a GitHub repo in a Playground environment. The GitHub Proxy handles fetching the plugin code and avoids CORS (cross-origin) issues that normally prevent direct downloads in the browser.

Example: Installing a GitHub-hosted Plugin

Let’s say we want to install a plugin called Gridify from a GitHub repository. We can do this by specifying a Blueprint step with a resource: url and pointing it to the GitHub proxy URL for that repo. For example:

{
  "landingPage": "/wp-admin/plugins.php",
  "login": true,
  "steps": [
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "url",
        "url": "<https://github-proxy.com/proxy/?repo=elpuas/gridify>"
      }
    }
  ]
}

What this Blueprint will do:

Quickly Test It Yourself: Try this one-click Playground URL to instantly launch a WordPress instance with the plugin fetched from GitHub:

<https://playground.wordpress.net/#{"landingPage":"/wp-admin/plugins.php","login":true,"steps":[{"step":"installPlugin","pluginData":{"resource":"url","url":"https://github-proxy.com/proxy/?repo=elpuas/gridify"}>}]}

Copy and paste the above URL into your browser’s address bar. After a moment, Playground will load WordPress, log you in, and you’ll find the Gridify plugin in the Plugins list of the dashboard.

How It Works

<https://github-proxy.com/proxy/?repo=elpuas/gridify&branch=develop>

You could similarly specify a tag or commit hash if needed.

Using this method, you can quickly test any plugin from GitHub in seconds, without leaving your browser or messing with local installations.

Using wp-now for Local WordPress Development (with Blueprints)

When working on a WordPress plugin or theme locally, setting up a development environment can be a hassle. wp-now simplifies this by allowing you to run WordPress instantly without installing a web server or database on your machine. It uses a WebAssembly-powered PHP and a lightweight SQLite database, which means no Apache, no MySQL – just a quick environment that runs in a container under the hood.

Think of wp-now as the local CLI equivalent of Playground: it spins up WordPress on demand. And the great news is that wp-now also supports Blueprints!

Where Should the Blueprint Go?

To customize your wp-now setup, you’ll create a blueprint.json file and place it in the root of your project directory.

/my-plugin
  ├── blueprint.json   ← Blueprint file here
  ├── my-plugin.php
  ├── README.md
/my-theme
  ├── blueprint.json   ← Blueprint file here
  ├── style.css
  ├── functions.php
  ├── index.php

When blueprint.json is in place at the root, wp-now will detect it and apply those settings when starting the local environment.

Installing and Running wp-now

You don’t need to install anything globally if you don’t want to. Using npx (which comes with Node.js ), you can run wp-now on demand. Just navigate to your project’s root directory in your terminal and run:

npx @wp-now/wp-now start

This command will download and launch a WordPress instance in that directory. By default, it starts a clean WordPress with the latest version of core.

Tip: The first time you run wp-now, it might take a bit longer as it downloads the necessary components (WordPress core files, the PHP runtime, etc.). Subsequent starts are much faster since those components are cached locally.

Out of the box, wp-now start without any options will give you a WordPress site (usually on http://localhost:8881) with the latest WordPress and PHP 8.0. However, it won’t have any custom plugins or themes active, and it uses a fresh SQLite database. You can use a Blueprint to customize this setup (for example, to pre-install your plugin or use a specific WordPress version).

Using a Blueprint with wp-now

Blueprints allow you to define things like:

Let’s create an example blueprint.json for a plugin project. This Blueprint will ensure our local wp-now environment uses WordPress 6.5, PHP 8.2, sets a custom site title, and activates a specific theme:

{
  "$schema": "<https://playground.wordpress.net/blueprint-schema.json>",
  "login": true,
  "preferredVersions": {
    "wp": "6.5",
    "php": "8.2"
  },
  "siteOptions": {
    "blogname": "WP-Now Local Site"
  },
  "steps": [
    {
      "step": "installTheme",
      "themeData": {
        "resource": "wordpress.org/themes",
        "slug": "twentytwentyfive"
      }
    },
    {
      "step": "activateTheme",
      "themeFolderName": "twentytwentyfive"
    }
  ]
}

Here’s what this Blueprint does: it logs you in automatically ("login": true gives you an admin session), ensures WordPress 6.5 and PHP 8.2 are used, changes the site title to “WP-Now Local Site,” then installs and activates the Twenty Twenty-Five theme.

Running wp-now with a Blueprint

Once your blueprint.json file is in the root of your project, start wp-now with the Blueprint flag:

cd my-plugin   # or cd my-theme
npx @wp-now/wp-now start --blueprint=blueprint.json

This tells wp-now to load and execute the steps from your Blueprint as it starts up.

What will happen when you run that?

You should see your WordPress site launch in a browser window shortly after running the command. The active theme will be Twenty Twenty-Five, and you’ll be logged in as an admin user (with default credentials, usually username admin and password password for Playground environments).

Why Use wp-now with Blueprints?

Using wp-now together with Blueprints combines the convenience of instant local WordPress with the power of pre-configured setups:

I hope this deep dive into WordPress Playground Blueprints, GitHub plugin integration, and wp-now helps you in your WordPress development workflow. Whether you’re spinning up quick demos in the browser or streamlining your local development, these tools are here to make your life easier. Happy Coding!

Give and Share

Enjoyed this article? Share it with your friends and colleagues!

Buy Me a Coffee

If you found this article helpful, consider buying me a coffee!

Buy Me a Coffee

Recent Posts

You Might Not Need a Custom Block: The Block Bindings API
El Puas
WordPress
You Might Not Need a Custom Block: The Block Variations API
El Puas
WordPressCode