Introduction

Let’s imagine you are building a WordPress plugin (or theme) and you need a local WordPress environment to deploy your plugin and test it right inside the WordPress - you are building a WordPress plugin at least, right?

Usually, the process is next: on Windows machines, you would install some of the already pre-configured packages such as XAMPP or Mamp, on macOS and GNU/Linux systems - you can do the same or just set up a plain Apache (or Nginx) server and MySQL database straight from the command line on your machine and then install the WordPress manually.

This is fine most of the time, but imagine you are working on multiple projects? Each time you start a new project, you will need the repeat the same process over again, create the database, make the Apache hosts changes, install the WordPress core, set up your IDE to work with this new environment - it is too much work for such simple daily process.

What if you can automate this entire process with just one command? That is possible thanks to the fairly new, wp-env tool introduced by the WordPress core. Let’s see how it works.

About wp-env package

wp-env is an NPM (Node Package Manager) package that is using Node to start a local WordPress environment in any directory on the system of your choice. Besides the Node, you will need an active Docker daemon active. Docker installation won’t be covered in this article since it is a pretty straightforward process and can be done on any major operating system. I would suggest setting up the Docker according to official docs. This package is using the Docker virtualization technology, for that reason, both Docker and Node are required on the operating system.

Once the required dependencies are installed, let’s verify that they are available on our system by checking their versions:

Run the next two commands:

node -v

docker -v

You should get the next output:

The version of Node or Docker on your machine may be different, but as long as you are using the newer versions of these tools, Node 12 or greater - everything should work. Okay, let’s move to the next step.

Package installation

In order to run the wp-env, we must install the NPM global package first.

Let’s run the next command to accomplish that:

npm install -g @wordpress/env

The NPM system will process the command and install the latest version of the wp-env package for us:

Once the package is installed, we are ready to use it - let’s first verify that is properly installed in your system path by running the wp-env --version command, you should get the next output:

Since this is a global package, you can run it from any directory on your machine.

Environment Setup

To run our development environment, we need to navigate to the desired directory and run the next command from the terminal: wp-env start

If we run this command in an empty directory or a directory that doesn’t contain WordPress-related files, it won’t work. Let’s try:

As we see from the command output - we are unable to run the environment if the directory where are we trying to run the command doesn’t appear to be a WordPress installation, plugin or a WordPress theme.

Let’s fix that by creating an example plugin file.

First, create a new directory: mkdir my-plugin

Inside the plugin directory, let's create an index.php file with a sample plugin code. It must be a valid WordPress plugin file. In the example, I've inserted only the plugin headers which is enough for us to test the wp-env tool. The plugin development is not the main topic of this blog post, for more information on plugin development please visit the WordPress Developer pages.

Now, let's try to run the wp-env start command once again:

wp-env start

This time - it works! We have a valid plugin file within a directory and the wp-env tool is now able to spin up the Docker containers with the full version of the WordPress CMS. In this case, we can see that this action took less than a minute - sweet!

WordPress is Ready

If we go to the URL localhost:8889 we will see that the WordPress is running and that we are ready to develop our plugin:

To access the WordPress Dashboard itself, you will need to use the next credentials. This is the same for each default installation via wp-env tool, but it can be customized:

(Username: admin, Password: password).

Let's verify that Dashboard is accessible:

Awesome! Everything is running as in normal flow, but from the start to finish you will need less than a minute compared to the previous stacks where you'll manually need to install every single module (server, database, core) in order to run the development site in the local environment which takes much longer. With this tool in mind, your process is now fully automatized.

For more information about the advanced options available within this tool, please visit the official documentation pages on Github. If you think this post was useful, do not forget to share it with your friends and colleagues!