How to create custom WordPress Blueprints

WordPress Studio supports WordPress Playground Blueprints. WordPress Studio runs them with its own Blueprint runner on native PHP. Blueprints in WordPress Studio help you:

Streamline repeatable setups: Create Blueprints for common site types (like blog, portfolio, or store) to start new WordPress Studio projects more efficiently.
Keep teams aligned: Add a blueprint.json file to your project’s GitHub repository, whether you’re building a plugin, theme, or full site. It scaffolds the same environment every time, so teammates can start building a plugin, theme, or full site in minutes, while version control keeps changes reviewable and consistent.
Simplify demos and testing: Launch WordPress Studio with the exact theme, plugins, and sample content you need. Reproduce bugs or confirm fixes with a reliable, repeatable setup.

This guide will teach you the basics of creating a custom Blueprint and provide additional resources where you can learn more.

What are Blueprints?

A Blueprint is a JSON file that defines a WordPress site’s setup. Within a Blueprint, you can configure settings such as your preferred WordPress and PHP versions. You can also specify a list of steps to run when the site is created, like installing and activating plugins and themes, setting site options, importing demo content, and running PHP or SQL queries.

Blueprints are written using a public JSON schema, standardizing their use across Playground, WordPress Studio, and beyond.

This minimal example configures the preferred WordPress and PHP versions, installs and activates the WooCommerce plugin and the Pendant theme, and sets the admin color scheme to “Modern.”

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "login": true,
  "preferredVersions": {
    "php": "8.3",
    "wp": "latest"
  },
  "steps": [
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "wordpress.org/plugins",
        "slug": "woocommerce"
      },
      "options": {
        "activate": true
      }
    },
    {
      "step": "installTheme",
      "themeData": {
        "resource": "wordpress.org/themes",
        "slug": "pendant"
      },
      "options": {
        "activate": true
      }
    },
    {
      "step": "updateUserMeta",
      "meta": {
        "admin_color": "modern"
      },
      "userId": 1
    }
  ]
}

Key things to know:

preferredVersions lets you predefine the PHP and WordPress versions.
steps is where the magic happens. You can log in, install or activate plugins and themes, import WXR content, set options, run PHP, and more. For instance, the example demonstrates installing WooCommerce and the Pendant theme, and adjusting the admin color scheme. Check out the Step Library for each available action with examples.

WordPress Playground offers an interactive Blueprint builder, allowing you to test various Blueprint setups. It’s a great way to validate your custom Blueprints before running them in WordPress Studio.

Preview Blueprint

Preview and download this Blueprint using the button above. Once downloaded, you can use it to create a new site in WordPress Studio. For detailed instructions, refer to the site creation flow in WordPress Studio.

Blueprint changes in WordPress Studio

The majority of features offered by Blueprints work in WordPress Studio the same way they do on https://playground.wordpress.net. The following table highlights the changes WordPress Studio applies:

Property	Why it’s changed by WordPress Studio
features → networking	Networking is always enabled and can’t be turned off, so users can always install plugins and themes.
features → intl	WordPress Studio’s PHP always includes the Intl extension, so this setting has no effect.
preferredVersions → php	WordPress Studio runs PHP 8.2 to 8.5. Any other version, or `latest`, uses WordPress Studio’s default PHP version (8.4).

Additional resources

Blueprints can be simple like the example above or as sophisticated as your workflow requires. The Playground documentation provides a clear overview of Blueprint JSON format, a quick start tutorial, and detailed references. If you want to create your own Blueprints or explore examples from the WordPress community, see the resources below:

Leveraging AI tools like the WordPress Studio Code is a great way to get help building custom Blueprints. Simply ask it to write a Blueprint for you:

Can you write a Playground blueprint for me in a JSON file that installs the latest default theme and the WooCommerce plugin?

There are also several community projects that provide a user interface for creating Blueprints, which are worth checking out:

For those following the WordPress Playground project closely, you may be aware that a new version of Blueprints is under development. As soon as Blueprints v2 is stable in Playground, support will be added to WordPress Studio in a subsequent release. All v1 Blueprints will remain supported.