I think the deepest way of learning something is by attempting to write about it or to teach others and since I was out-of-date with this subject I’ve decided to do a freshup about what a WordPress plugin or theme should contain in its development repository.

Let’s start with an obvious spoiler for people who are just starting in this field, in order to build a modern stack of tools for WordPress development you need to have on your device things like:

  • NodeJS
  • Docker
  • git – if you want to be modern
  • svn – if you want to publish on wordpress.org

I also think that your life would be easier in the WordPress development world if you understand the basics of:

  • NPM / Yarn
  • WebPack
  • Composer
  • ReactJS

WordPress environment

I want to say that the most important thing nowadays is to have a WordPress environment ready to start a click and even if the coolest thing at the moment is Playground(which is useful to end users), I’m rather happy to talk about the @wordpress/env npm package which is more useful to developers.

This npm package relies on Docker to start a WordPress instance as fast as you can blink. It can start a WordPress site based on a certain configuration held in the .wp-env.json file which looks like this:

  "core": "https://wordpress.org/wordpress-5.4-beta2.zip",
  "plugins": [
  "port": 1000,
  "testsPort": 1001,
  "config": {
    "WP_DEBUG_DISPLAY": true

No more docker-compose headaches, no more different setups between developers, and hopefully, we will hear the phrase “But it works on my machine!” fewer times.

This is just a glimpse of what it can do, and maybe the first thing that comes to your mind is “Hey, I can replace Xamp or LocalWP with wp-env” which would not be wrong at all. Basic configurations are possible like:

  • PHP version.
  • WordPress version.
  • List of plugins to start with.
  • The theme of the started site can be local or from the WordPress repository.
  • Local port to start on.

But in my opinion, the most important thing is that it opens the possibility to run scripts, unit tests, code coverages, or continuous integration/continuous delivery way easier than ever. Some advanced things we will be able to do with wp-env:

  • Run wp-cli commands at different lifecycles of the instance.
  • Import settings or content before starting the website.
  • Compile assets, check coding styles, or do anything within the npm run spectrum before starting the instance. Basically, prepare the product for production before testing it.
  • Run Unit tests or end-to-end tests.
  • Xdebug and IDE support is available. This should make things easier to debug.
  • PHP and Apache custom configurations.

All of these combined with the power of GitHub actions will help you make a production setup that will make even some big corporations envy you.

By the way, all of this is free and open-source 😉 

Simple start

Assuming you have Docker running and NodeJs installed on your machine it is surprisingly simple to start a WordPress instance.

First, we need to make sure we have wordpress-env installed globally, so we open the terminal and run this only once:

npm -g i @wordpress/env

Whenever you need a WordPress instance with a user admin with password password just run this:

npx wp-env start --update

Here’s a preview, isn’t this the fastest way of running a testing ground?

A gif displaying how you can start a WordPress instance with wordpress-env.

Note: This preview comes from a macOS environment, but I’ve been testing it on a Windows machine with Docker and WSL 2 and it works as well as on my Macbook.

Unexpected wrap-up

I wanted to write a long article with many examples of how could we use this tool but now I’ve changed my mind. I will end this one right now and I’ll come back with articles on some specific examples of how to use the @wordpress-env package because I feel like each example would require a better description.

Let’s keep up with this list:

  • To be continued