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.
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
}
}
]
}
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.
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.
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
}
}
]
}
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.
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.
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.
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-now 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-now/wp-now start
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.