Setting up a new developer environment to contribute to WPGraphQL..

I just announced that I am now employed by WP Engine to work on WPGraphQL.

With new employment comes a new Macbook, which I need to setup as a dev machine to continue working on WPGraphQL.

It’s always a tedious process to get a new computer setup to be an effective developer, so I thought I’d record all the steps I take, as I take them, and hopefully provide some help to others.

Local WordPress Environment

One of the first things I need to do to work on WPGraphQL, is have a local WordPress environment.

For the past 3 years or so, my preferred ways to setup WordPress locally is to use Local, a desktop application that makes it easy to setup WordPress sites with a few button clicks.

I enjoy Local so much, I even picked it as my “Sick Pick” on the episode about WordPress and GraphQL!

When working locally, I usually have a number of different WordPress sites with different environments. For example, I have a site that I use locally to test WPGraphQL with WPGraphQL for Advanced Custom Fields, and another environment where I test things with WPGraphQL and WPGraphQL for WooCommerce. Having different sites allows me to separate concerns and test different situations in isolation.

However, the constant is WPGraphQL. I want to be able to use the same version of WPGraphQL, that I’m actively making changes to, in both environments.

This is where symlinking comes in.

In the command line, I navigate to my local site’s plugins directory. For me, it’s at /Users/jason.bahl/Local Sites/wpgraphql/app/public/wp-content/plugins

Then, with the following command, I symlink WPGraphQL to the Local WordPress site: ln -s /Users/jason.bahl/Sites/libs/wp-graphql

This allows me to keep WPGraphQL cloned in one directory on my machine, but use it as an active plugin on many Local WordPress sites. As I create more sites using Local, I follow this same step, and repeat for additional plugins, such as WPGatsby or WPGraphQL for Advanced Custom Fields.

XDebug for PHPStorm Extension

PHPStorm is my IDE of choice, and Local provides an extension that makes it easy to get PHPStorm configured to work with XDebug. I recommend this extension if you use Local and PHPStorm.

TablePlus Extension

I used to use SequelPro, but have been transitioning to use TablePlus, and Local has a community extension that opens Local databases in TablePlus.


For as long as I’ve been working on WPGraphQL, PHPStorm has been my IDE of choice. I won’t get into the weeds, and you are free to use other IDEs / Code Editors, but I find that PHPStorm makes my day to day work easier.

Pro tip: To save time configuring the IDE, export the settings from from PHPStorm on your old machine and import them on your new machine.


SourceTree is a free GUI tool for working with code versioned with Git. While Git is often used in the command line, sometimes I like to click buttons instead of write commands to accomplish tasks. I also find it super helpful to visualize Git trees to see the status of various branches, etc. I find the code diffs easier to read in SourceTree than in the command line too, although I like Github’s UI for code diffs the best.

In any case, I use SourceTree daily. I think it’s fantastic, and you can’t beat the price!

Note: If you try using SourceTree before using Git in the command line, it might fail. This is because you need to add (or whatever git host you use) to your ssh known hosts. You can read more about this here.


Local sets up MySQL for each site, but for running Codeception tests for WPGraphQL, I like to have a general MySQL install unassociated with any specific Local site that I can configure for Codeception to use.

I download and install MySQL v5.7.26 for macOS here.

I then ensured that I updated my .zshrc file to include this export, as described here, to ensure the mysqld command will work.


I used to use SequelPro, but it’s been deprecated, so I’ve begun using TablePlus. You can download it here.

Docker Desktop

WPGraphQL ships with a Docker environment that developers can spin up locally, and the tests also have a Docker environment so they can be run in isolation.

In order to spin up the local Docker environment or run tests with Docker, Docker Desktop needs to be installed and logged into.


Homebrew is a package manager for MacOS (or Linux). It makes it easy to install packages that are useful for development on a Mac.

I used Homebrew to install the below packages.

Command Line Tools for XCode

This is something I seem to forget almost any time I setup a new Mac. When trying to install things from the command line, I’m always prompted to install Command Line Tools for Xcode and agree to their licensing. For me, as I was installing Homebrew, I was prompted to Download and Install this. If you want to install it separately, follow these instructions.


Since WPGraphQL is maintained on Github, Git is essential to my daily work.

With Homebrew installed, I use it to install Git, which is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

Having git installed locally allows me to clone repositories from Github to my local machine, make commits to code, and push code back up to Github.

In order to use Git with 2-Factor Authentication enabled, I also had to get SSH keys setup for Github.


Composer is a PHP package manager. WPGraphQL uses Composer for test dependencies, so it’s important to have Composer installed in order to run tests. I used the command brew install composer to install Composer.

Note: I also had to make sure I was running a version of PHP that the zip module, so I followed these steps to get that working.

Node & NVM

Since I do a lot of work with JavaScript applications, such as Gatsby and the WP Engine Headless Framework, having Node installed locally is a must, and having nvm (Node Version Manager) to allow switching Node versions quickly is very helpful.

I followed this guide to get Node and NVM installed using Homebrew.

Time to contribute!

Now that I have my local environment setup and all my regular tools, I’m ready to contribute to WPGraphQL again!