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.