How to Setup an ideal WordPress Development Environment

WordPress is not my primary development environment. I only go in when I need certain functionality or design fixes for my own site, and by far the most painful part is getting set up. (Maybe I'm just a N00b). The biggest problem I had with my former development environments was not being able to access the source code and poke around.

Learn to code with our beginner friendly tutorials on programming, Linux, Docker, and more

Sure, I can READ it on Github, but it's hard for me to figure out what's going on by just reading. I need to be able to interact with the WordPress source code. Also, being the large beast that WordPress has become, documentation can't keep up, so it's necessary to access the source code... So here's how I've been able to do that by setting up an "ideal WordPress Development Environment".

Edit: I spent way too many hours debugging NPM errors on a new windows machine to get this setup working. The solution I found here appears to be npm install --global --production windows-build-tools and if your install failed before doing this, you'll probably have to DELETE the $HOME/.node-gyp folder (when you install something that needs it, it will automatically be re-installed.

What you need:

WordPress-Develop Github Repository

Gutenberg Github Repository

Step 1. Setup the WordPress-Develop repository locally.

go through their instructions. Currently you just need Node.js and Docker installed and running. So do that and come back.

clone the wordpress-develop repository. I created a folder on my Desktop where the entire setup will go called "hello-wordpress" and then inside "hello-wordpress" is where I cloned the wordpress-develop repository. Then cd in and setup the environment as it explains in the readme:

mkdir hello-wordpress
cd hello-wordpress
git clone https://github.com/WordPress/wordpress-develop.git
cd wordpress-develop
npm install
npm run watch

Note that we skip a lot of instructions on the wordpress-develop docs page because we're going to be using Gutenberg for the Docker setup. If we were to run the other commands in the wordpress-develop then they would interfere with Gutenberg.

npm run watch is important because it gives us the "build" folder inside wordpress-develop that the gutenberg code relies on.

that's as far as we go in these instructions for now. Next step is to download and install Gutenberg Core.

Now change OUT of the wordpress-develop folder and back INTO hello-wordpress... Then clone gutenberg:

cd ../
git clone https://github.com/WordPress/gutenberg.git
cd gutenberg
npm install

Now we'll want to setup where our plugin code goes. Make another folder inside the "hello-wordpress" folder called "plugins", and create your plugins in there. Mine will be "my-cool-plugin" So here's my basic plugin code in this file: hello-wordpress/plugins/my-cool-plugin/my-cool-plugin.php

<?php
/**
 * Plugin Name: My cool plugin
 * Plugin URI: https://truthseekers.io
 * Description: cool plugin stuff
 * Author: John
 * Author URI: https://truthseekers.io
 */

That should be enough to activate our plugin.

Next, we need to "connect" our plugins folder with Gutenberg. We do that in .wp-env.override.json inside our gutenberg folder. This file doesn't exist by default (as of writing this) so we'll need to create it. (in the same level as the package.json file)

{
    "core": "../wordpress-develop/build",
    "plugins": [
        ".",
        "../plugins/my-cool-plugin"
    ]
}

The "core" line tells the Gutenberg plugin that the rest of the wordpress project is located in the wordpress-develop/build folder. That's where it will grab all the source...

Each element in the "plugins" array is a directory for each plugin that you want activated. So.. "." for the gutenberg plugin, and then the location of the plugin you're developing.

Almost done. Now we just need to go back to the gutenberg folder and start things up.

npx wp-env start
npm run dev

Now you can access the WP dashboard area by visiting localhost:8888 and use "admin" and "password" as the credentials. Go visit the "plugins" section to see your plugin is activated. To test, go to the "wordpress-develop" folder, and run a die statement in wp-includes/blocks.php

And refresh your admin area and hopefully you'll see it:

Now test Gutenberg code. In the gutenberg folder, inside packages/blocks/src/index.js run a console.log...

and you should see the results of your console.log inside the dev tools when you're in the gutenberg editor area.

When you're done coding, kill everything with CTRL+C to kill npm run dev.. Then npx wp-env stop to kill Gutenberg/Docker. Finally,

hit CTRL+C in wordpress-develop to kill wordpress-develop.

To start everything back up, npm run watch in wordpress-develop, then inside "gutenberg" run npx wp-env start and then npm run dev

You should have access to wp-cli utilities within the Gutenberg folder.

Don't miss our next tutorials!