Skip to main content

WordPress Playground for Theme Developers

The WordPress Playground is an innovative tool that allows theme developers to build, test, and showcase their themes directly in a browser environment.

This guide will show you how to use WordPress Playground to improve your theme development workflow, create live demos to showcase your theme, and simplify the theme review process.

info

Discover how to Build, Test, and Launch your products with WordPress Playground in the About Playground section

Launching a Playground instance with a theme​

Themes in the WordPress themes directory​

With WordPress Playground, you can quickly launch a WordPress installation using any theme available in the WordPress Themes Directory. Simply pass the theme query parameter to the Playground URL like this: https://playground.wordpress.net/?theme=disco.

You can also load any theme from the WordPress themes directory by setting the installTheme step of a Blueprint passed to the Playground instance.

{
	"steps": [
		{
			"step": "installTheme",
			"themeData": {
				"resource": "wordpress.org/themes",
				"slug": "twentytwenty"
			},
			"options": {
				"activate": true,
				"importStarterContent": true
			}
		}
	]
}

   Run Blueprint   

Themes in a GitHub repository​

A theme stored in a GitHub repository can also be loaded in a Playground instance with Blueprints.

In the themeData property of the installTheme blueprint step, you can define a url resource that points to the location of the .zip file containing the theme you want to load in the Playground instance.

To avoid CORS issues, the Playground project provides a GitHub proxy that allows you to generate a .zip from a repository (or even a folder inside a repo) containing your or theme.

tip

GitHub proxy is an incredibly useful tool to load themes from GitHub repositories as it allows you to load a theme from a specific branch, a specific directory, a specific commit or a specific PR.

If your theme is hosted on GitHub, you can automatically add preview buttons to your pull requests using the Playground PR Preview GitHub Action. This lets reviewers test your changes instantly without any setup. See Adding PR Preview Buttons with GitHub Actions for details.

For example the following blueprint.json installs a theme from a GitHub repository leveraging the https://github-proxy.com tool:

{
	"steps": [
		{
			"step": "installTheme",
			"themeData": {
				"resource": "url",
				"url": "https://github-proxy.com/proxy/?repo=Automattic/themes&branch=trunk&directory=assembler"
			},
			"options": {
				"activate": true
			}
		}
	]
}

   Run Blueprint   

A blueprint can be passed to a Playground instance in several ways.

Setting up a demo theme with Blueprints​

When providing a link to a WordPress Playground instance with a specific theme activated, you may also want to customize the initial setup for that theme. With Playground's Blueprints you can load, activate, and configure a theme.

tip

Some useful tools and resources provided by the Playground project to work with blueprints are:

  • Check the Blueprints Gallery to explore real-world code examples of using WordPress Playground to launch a WordPress site with a variety of setups.
  • The WordPress Playground Step Library tool provides a visual interface to drag or click the steps to create a blueprint for WordPress Playground. You can also create your own steps!
  • The Blueprints builder tool allows you edit your blueprint online and run it directly in a Playground instance.

Through properties and steps in the blueprint, you can configure the initial setup of your theme in the Playground instance.

info

To provide a good demo of your theme via Playground, you may want to load it with default content that highlights the features of your theme. Check out the Providing content for your demo guide to learn more about this.

resetData​

With the resetData step, you can remove the default content of a WordPress installation in order to import your own content.

"steps": [
	...,
	{
		"step": "resetData"
	},
	...
]

   Run Blueprint         See blueprint.json   

writeFile​

With the writeFile step, you can write data to a file at a specified path. You may want to use this step to write custom PHP code in a PHP file inside the mu-plugins folder of the Playground WordPress instance, so the code is executed automatically when the WordPress instance is loaded. One of the things you can do through this step is to enable pretty permalinks for your Playground instance:

"steps": [
	...,
	{
		"step": "writeFile",
		"path": "/wordpress/wp-content/mu-plugins/rewrite.php",
		"data": "<?php /* Use pretty permalinks */ add_action( 'after_setup_theme', function() { global $wp_rewrite; $wp_rewrite->set_permalink_structure('/%postname%/'); $wp_rewrite->flush_rules(); } );"
	},
	...
]

   Run Blueprint         See blueprint.json   

updateUserMeta​

With the updateUserMeta step, you can update any user metadata. For example, you could update the metadata of the default admin user of any WordPress installation:

"steps": [
	...,
	{
		"step": "updateUserMeta",
		"meta": {
			"first_name": "John",
			"last_name": "Doe",
			"admin_color": "modern"
		},
		"userId": 1
	},
	...
]

   Run Blueprint         See blueprint.json   

setSiteOptions​

With the setSiteOptions step, you can set site options such as the site name, description, or page to use for posts.

"steps": [
	...,
	{
		"step": "setSiteOptions",
		"options": {
			"blogname": "Rich Tabor",
			"blogdescription": "Multidisciplinary maker specializing in the intersection of product, design and engineering. Making WordPress.",
			"show_on_front": "page",
			"page_on_front": 6,
			"page_for_posts": 2
		}
	},
	...
]

   Run Blueprint         See blueprint.json   

There's also a siteOptions shorthand that can be used instead of the setSiteOptions step.

plugins​

With the plugins shorthand you can set a list of plugins you want to be installed and activated with your theme in the Playground instance.

"plugins": ["todo-list-block", "markdown-comment-block"]

   Run Blueprint         See blueprint.json   

You can also use the installPlugin step to install and activate plugins for your Playground instance but the shorthand way is recommended.

login​

With the login shorthand you can launch your Playground instance with the admin user logged in.

 "login": true,

   Run Blueprint         See blueprint.json   

You can also use the login step to launch your Playground instance logged in with any specific user.

tip

The "Stylish Press" and "Loading, activating, and configuring a theme from a GitHub repository" examples from the Blueprints Gallery are great references for loading, activating, importing content, and configuring a block theme on a Playground instance.

Theme development​

Local theme development and testing with Playground​

From the root folder of a block theme's code, you can quickly load locally a Playground instance with that theme loaded and activated. You can do that by launching, in a theme directory, the @wp-playground/cli command from your preferred command line program or the Visual Code Studio extension from the Visual Studio Code IDE.

For example:

git clone git@github.com:WordPress/community-themes.git
cd community-themes/blue-note
npx @wp-playground/cli server --auto-mount

Design your theme using the WordPress UI and save your changes as Pull Requests​

You can connect your Playground instance to a GitHub repository and create a Pull Request with the changes you’ve done through the WordPress UI in the Playground instance, leveraging the Create Block Theme plugin. You can also make changes to that theme and export a zip.

Note that you'll need the Create Block Theme plugin installed and activated in the Playground instance in order to use this workflow.

tip

Check About Playground > Build > Save changes done on a Block Theme and create GitHub Pull Requests for more info.