Setup a Gutenberg WordPress Development environment with Source Code

In this post I’m going to show you how to setup a development environment that allows you to interact with the source code while you develop Gutenberg blocks. Documentation is not always good so the source code really helps.

We can use wp-scripts to quickly spin up a local WordPress development environment using Docker. Here’s how we do it:

Get our best tutorials & crash courses to get up and running quickly

Install Docker and Docker-compose

Get your Docker installation here. Linux users will have to figure this part out on their own.

Once you’ve completed the installation, test that Docker and docker-compose work properly with the following terminal commands:

$ docker run hello-world  # this should output a bunch of text saying your install is working properly
$ docker-compose -v #this should return something like "version 1.25.4" 

If both of those give some sort of output message saying there’s a version, and “Hello from Docker!” then you’re ready to go. Now choose a location on your system where you want to place your “plugins” folder. We’ll call our root directory “wpdev” and place it on the Desktop. (I’m on Windows so commands may look a little different)

$ cd .\Desktop\
$ mkdir wpdev
$ cd wpdev

Make sure to have Node.js and NPM installed. Inside your wpdev folder, clone the Gutenberg source code. (It’s gonna take a while)

$ git clone https://github.com/WordPress/gutenberg/

From here you can use the “getting started” guide, but I’m going to explain it here because there’s a few other things we’re going to do. CD into the gutenberg folder where all the source code is, and get it prepped:

$ cd gutenberg
$ npm install

Now we’re going to use the env npm module to wire up a Docker environment. This will take care of your entire local development environment. Docker and Docker-compose have to be running on your machine in order for this to work, so make sure those docker commands above are working. Once that’s squared away run these commands.

$ npx wp-env start
$ npm run dev

npx wp-env start wires up the docker images and containers to create the whole environment for you to develop in. After you’ve ran the command you should be able to see your docker containers by running $ docker ps in your terminal

npm run dev allows you to see the effects of your changes in the source code. WordPress uses Webpack, which takes all of your development files and smooshes them together into a build folder. Every time you change the source code, Webpack needs to be notified so it can adjust the build files.

Now you should be able to login to your wordpress environment at http://localhost:8888 with a username of “admin” and password of “password”. You should also be able to interact with the source code. Put a console.log in the registerBlockType() function inside packages -> blocks -> src -> api -> registration.js file of your gutenberg source code.

export function registerBlockType(name, settings) {
	console.log("hello from the source code!");
	settings = {
// ...

Now if you open your dev tools inside the create new post area you should see your console.log.

Step Two: Setup Your Custom Gutenberg Plugin

Unless you’re developing the core of Gutenberg you’ll want to create your own plugin. I like my plugin folders as siblings of the Gutenberg source, so in the wpdev folder I’ll create a plugin folder called “test-plugin”. Inside test-plugin I’ll make a file called test-plugin.php

<?php
/**
 * Plugin Name: Test Plugin Blocks
 * Plugin URI: https://truthseekers.io
 * Description: Kick some booty blocks
 * Author: John
 * Author URI: https://truthseekers.io
 */

if (!defined('ABSPATH')) {
    exit;
}
// Rest of plugin code here.

Now we need a way to connect our plugin to the rest of our code. We can connect our custom plugin to our Gutenberg source code by creating a .wp-env.override.json file inside the gutenberg folder. replace “../test-plugin” with the relative path to your plugin.

{
    "core": "WordPress/WordPress#master",
    "plugins": [
        ".",
        "../test-plugin"
    ]
}

The only thing left to do is turn off the docker containers and restart them. Since I run npm for gutenberg in the same directory, I’ll restart it too, but that’s not strictly necessary. Hit Control + C to turn off the server, then restart docker: (Do this in your terminal inside your gutenberg folder)

$ npx wp-env stop
$ npx wp-env start
$ npm run dev

If everything went well your “test plugin” should be activated. Check to see.

Now in your custom plugin you have to setup all the Javascript to work with Gutenberg blocks. The wp-scripts package should handle most, if not all of the WordPress dependencies for you. Check out this documentation for help: Packages scripts documentation and Gutenberg Javascript Setup. I’ll work through setting up Webpack and blocks and all that in another tutorial, but those two links should help you get started.

When you import dependencies for your gutenberg blocks, do NOT do anything like $ npm install @wordpress/blocks. That’s why we pulled the Gutenberg source code to our local machine. Take a look at the code below:

const { registerBlockType } = wp.blocks;
const { addFilter } = wp.hooks;

This will connect to the Gutenberg plugin and pull in the dependencies from there, as long as you have it listed in the .wp-env.override.json file. And since that source code is listening for changes (because you ran $ npm run dev) you’ll be able to debug that code as well. Hopefully that makes sense. You can see below how the dependencies are getting pulled in by looking at Gutenberg’s package.json file. We have everything we need right in the plugin.

Want More Tutorials?

Get our best crash courses and tutorials

(Source Code Provided)

Missing pieces

This setup isn’t perfect yet, but I’ll update this article as I find improvements. So far this only works for Gutenberg because the rest of the PHP source code is in Docker. Also, accessing the database is kind of a pain in the butt. We don’t have phpmyadmin or Adminer setup so we’re stuck stepping into our containers or possibly using wp-cli, but I like using the docker container. So, if you need to run SQL queries, then in your terminal, first figure out the name of your container:

$ docker ps

You want the container with the “mysql” in it. My container name is this: d0e2a41dd31c20271480049dea31bdb9_mysql_1 So I’ll grab that and run this command:

$ docker exec -it d0e2a41dd31c20271480049dea31bdb9_mysql_1 /bin/bash

This basically says Run a bash prompt inside the mysql container. From here you just run the mysql command to enter into a mysql session just like you would any other terminal. Just hit enter when it prompts you for the password since we don’t have a password in development. Then… select your database and run the queries you want.

$ mysql -u root -p
$ use wordpress;
> SELECT post_title FROM wp_posts;

Then when you’re done in the container you can press Ctrl + c to exit the mysql session, and type exit to exit out of the docker container.

That’s all! Do you have a better WordPress development workflow? If so, please share it in the comments.

Leave a Comment

Your email address will not be published. Required fields are marked *

want more details?

Fill in your details and we'll be in touch

%d bloggers like this: