Setting Up Development Environment for Gutenberg on Windows

Introduction

There is some good documentation available on getting started with WordPress development in Gutenberg but not quite enough (imho) on accomplishing this on Windows. I’ve attempted to lay out step by step the process below.

For the official documentation see:

Install Git

Download and install a copy of Git.

Make a Fork of the Repository

You can’t make contributions directly to the Gutenberg repository so create a fork. There is a button to do so at the top right of the Gutenberg repo. This creates a copy of the repo under your account.

Get the Repository

Open Git Bash. You’ll be dropped into the User folder on your hard drive, usually at path like: C:\Users\username\. You’ll need to navigate to wherever your code is stored, for example cd /c/code.

You can then clone the contents of your repository by doing something like this: git clone https://github.com/username/gutenberg/gutenberg.git. This will create a folder within the folder you run this command in, so if you are in /c/code your Gutenberg repo will be cloned into /c/clone/gutenberg.

This can take a few minutes, the Gutenberg repo is quite large.

Create a Branch

To keep your fork easily syncable with the WordPress Gutenberg repo, don’t make edits on master. Instead create a branch and make edits to this branch.

git branch somename
git checkout somename

Getting a WordPress/Gutenberg Local Environment Running

Install Chocolatey for Package Management

Chocolatey is a package manager that can install/uninstall/manage applications for you. Download and install.

Install Python

Some of the node modules used by Gutenberg require Python. Theoretically you can install Python using choco install python but I was having some issues with Node seeing this install for some reason (even though it was added to the path) so ended up downloading the Python 3.8 installer from python.org and installing it directly (it is very possible the issue was user error on my part, so give choco a try if you like and let me know if you succeed!).

Install NVM for Windows

We could download and install Node ourselves, but if we use choco install nodejs we end up with a too recent version that throws errors for some Node modules. Instead we’ll use choco to install nvm and use nvm to install node/npm: choco install nvm.

Unfortunately, nvm didn’t seem to get installed in the system path, so I had to do this manually. I use rapidee for this purpose and setting the path to C:\ProgramData\nvm worked spendidly.

Install Node and NPM

As I mentioned previously using the latest version of npm can cause some problems when installing modules used by Gutenberg, so we’ll specify our desired version (lets go with whatever the LTS release is at the current time): nvm install 12.13.1.

Setting Up Docker

We need to download Oracle’s VirtualBox to use with Docker for Windows: choco install virtualbox. Theoretically we could use Microsoft’s Hyper-V but I’ve tried several times without success – and I don’t seem to be alone!

Then we need to install Docker itself: choco install docker-machine. Note that we are downloading docker-machine not docker, the original Docker package is now deprecated on Chocolatey.

Installing the npm Packages

Now we want to install the npm modules that Gutenberg requires so from within the local Gutenberg repo directory we run npm install. Hopefully this should run through for you successfully.

Note: If you run into issues and have followed all the steps above, try closing out the current command prompt window and opening a new one.

Building Gutenberg

Assuming everything has worked correctly thus far we can build Gutenberg for production using npm run build.

A Local Install of WordPress

Ideally we want to be able to work off a local copy of WordPress. One way to accomplish this is by using the environment included with Gutenberg. To run it enter npm run env install.

Once completed you should be able to navigate to http://localhost:8889 and see your local WP instance.

Accessing Storybook

Run npm run storybook:dev, it will open a browser window automatically.

Whoops!

Sometimes (aka, we’ve been editing on master of our fork instead of a branch) we may find our repository has become unsynced with the upstream repository (WordPress/gutenberg). In this case we can rebase our repo locally on the upstream repository.

Theoretically one should be able to accomplish this using the instructions in Syncing a fork by GitHub. This didn’t work for me.

The first problem will probably be that you haven’t configured remote to know about WordPress’ repo, so you need to add it, see Configuring a remote for a fork by GitHub.

The next thing to do is rebase your fork using WordPress’s repo. See this article on StackOverflow on rebasing a fork.

%d bloggers like this: