How to create custom WordPress Blueprints

WordPress Studio is powered by WordPress Playground, which supports Blueprints. Blueprints in Studio help you:

• Streamline repeatable setups: Create Blueprints for common site types (like blog, portfolio, or store) to start new 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 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, setting the site’s language to Spanish, 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 Studio.

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

Blueprint limitations in Studio

The following table highlights how Blueprints function differently in Studio compared to playground.wordpress.net, as of version 1.6.0:

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:

• Blueprints overview and quick start tutorial
• Data format and schema
• Steps reference and visual Step Library
• Example Blueprints and the community gallery

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

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

• WordPress Playground Step Library
• Pootle Playground
• Block Based Visual Blueprint Builder