Quick and easy local WordPress development with wp-env

Sometimes you get a great idea, one that is so compelling that you really want to try it out right now! And since you’re a WordPress developer, that means you want to start coding up a quick proof of concept straight away.

The last thing you want to do is waste your time and creative energy setting up a new local WordPress instance. Depending on your local environment, that process can involve a variety of steps:

• downloading and installing WordPress,
• creating a database,
• editing the wp-config.php file,
• and more…

All of these things can be rather tiresome and none of them involve actually working on coding up your idea. Instead they’re things that hold you back, albeit temporarily, when what you really want to do is Just! Get! Coding! 

Local-dev options you’ve probably heard of

So how fast can you get coding with the local-development options that are out there now?

Local (by Flywheel) is pretty good. You only need to install it once and after that, you have a short and painless path to an up-and-running WordPress installation, though you do still have to launch the app first whenever you want a development environment.

MAMP/WAMP/XAMPP, on the other hand, is at the other end of the scale. WAMP and XAMPP require you to install Apache, PHP, and MySQL/MariaDB separately. MAMP is a little easier, since the Mac operating system comes with PHP and Apache. And then, every time you want a new WordPress site, you have to:

• download the WordPress files,
• install the WordPress files,
• and laboriously configure the WordPress files.

Furthermore, if you need to host several sites locally you may also have to set up separate virtual hosts in Apache. (Maybe you should have started by writing down that brilliant idea in a notes app! 😄)

Another disadvantage of both Local and MAMP/WAMP/XAMPP, and also of the other environments you might use, like Laravel Valet, DevKinsta, and the now sadly defunct DesktopServer, is that they all make you build your theme or plugin in the wp-content directory of your local WordPress installation.

Yes, it is possible to develop in another location, but then you then need to create a symlink in wp-content/themes or wp-content/plugins that points to the directory you’re developing in.

And you’re still not coding yet!

So what do you do if, like me, you you don’t want to have to set up a whole new WordPress installation for every idea you want to experiment with? And moreover, if you would rather keep all your development projects in a single, easy-to-back-up /Development directory?

Introducing wp-env

wp-env enables you to quickly spin up an almost instant WordPress environment from the command line, from whichever directory your project happens to be in, with zero configuration.

Gutenberg contributors developed wp-env to aid developers in creating blocks and contributing to Gutenberg, but it can be used for any plugin or theme project.

It’s an extremely convenient way of getting a WordPress installation up and running quickly and easily so that you can get on with the business of developing your new project.

As you’ll see a little later on, wp-env can also be included as a dev dependency in your project. This means that other developers collaborating on the project can clone it and spin up an identical environment.

Easy to install, easy to run

It’s extremely easy to install wp-env. But hold on, there’s a couple of prerequisites. 

wp-env requires Docker

Docker is used to package the WordPress installation that wp-env creates into a sandboxed process known as a container, which is a virtualized application consisting of a web server, a database, and WordPress itself.

Putting your installation into a container isolates it from other processes on your machine. This distinguishes wp-env from the other environments mentioned earlier which are not isolated in this way.

The container also enables the application state to persist across instances of the application. So the next time you you spin up wp-env, all your posts, pages, and other content will be right where you left them. 

Installing Docker

The easiest way to get set up with Docker is to install Docker Desktop. See the instructions for installing Docker Desktop on  Windows, macOS, and Linux.

wp-env requires Node/NPM

Node is how you install wp-env, and NPM is how you run it. In fact, everything you do with wp-env, you’ll do from the command line.

If you don’t already have Node/NPM installed head over there and follow the installation instructions.

And now, wp-env!

So once you have Docker and Node/NPM in place, you can install wp-env.

You can install it either locally to your project, or globally. Ideally you should install wp-env globally, because then you’ll have it available everywhere on your development machine for any project that you want to use it with.  

Global installation

To install wp-env globally enter this command in the terminal: 

npm -g i @wordpress/env

You can check that the installation has been successful with this command:

wp-env --version

Alternatively, you can list the globally installed NPM packages:

npm list -g

And now it’s simple to get WordPress up and running. Just run the command:

wp-env start

from the directory where you want to create your project.

Local installation

You can also install  wp-env locally to your project. In this case it’s only available to that one project, but you may prefer to keep the NPM global space clean. Installing locally also means that it will be a development dependency. Collaborators can then clone the project and be assured of an identical environment.

To install wp-env locally to the project enter this code from the project directory:

npm i @wordpress/env --save-dev

This will install wp-env as a development dependency to the project and the devDependencies property in package.json will be updated to include this:

"devDependencies": {
    "@wordpress/env": "^5.14.0"  
}

To run  wp-env locally type this command in the terminal:

npx wp-env start

Alternatively you could add it to the scripts property in package.json:

"scripts": {
    "wp-env": "wp-env"
}

Then, to run it, type:

npm run wp-env start

Using wp-env

Whether you installed it globally or locally to the project, this is what you should see in the terminal when the wp-env environment has started:

WordPress development site started at http://localhost:8888/
WordPress test site started at http://localhost:8889/
MySQL is listening on port 62378
MySQL for automated testing is listening on port 62379

The address for the development site will be http://localhost:8888/. Enter that into your browser’s address bar, and you’re good to go.

You can treat it just like any other WordPress site, and, as mentioned earlier, the containerisation provided by Docker ensures that the state, i.e. your content and settings, will persist across instantiations of wp-env that you run from the same directory.

You’ll have noticed that there’s a development site on port 8888 and a test site on port 8889. You may be wondering, why two separate sites? The difference between them is that in the test site, the wp-config values WP_DEBUG and SCRIPT_DEBUG are set to false. The test site gives you unit tests and end-to-end tests you can run automated tests against. The development site is for testing with your own content. Any content that you add yourself to the test site will be deleted on running the tests.

Using WordPress in the environment

To access the WordPress admin panel use http://localhost:8888/wp-admin. The logon credentials are “admin” and “password”—please don’t use these for your online banking! 😄

Once you’re logged in, you’ll find that the theme or plugin you’re working on has been automatically activated. So you can simply get on with working on your project.

When you’re done developing you can stop  wp-env by typing:

wp-env stop

in the case of a global installation, or with one of the following in the case of a local-to-project installation:

npx wp-env stop

npm run wp-env stop

Which you use depends on how you started it in the first place.

Wrap-up

And that’s pretty much it. It’s as simple as that. wp-env is simple to install and super-simple to use. It neatly circumvents all the setup and configuration you need to do to get your WordPress installation up and running with other environments, and it lets you do your building wherever you like, not just in the wp-content directory.

There’s more!

There’s more that you can do with wp-env. For a full list of the commands, see the wp-env page in the Block Editor handbook.  Particularly useful is:

wp-env destroy

which will remove the Docker container when you don’t need it any more.

You can even run WP-CLI commands with:

wp-env run cli [command]

If you need to customize your WordPress installation, for example, if you want certain plugins to be installed and activated whenever you spin it up, you can specify a .wp-env.json file in the directory you run wp-env from. You can find out more in the section of the handbook page that talks about this.

If you’d like to delve into the inner workings of wp-env, the code is a package in the Gutenberg repository on GitHub.

Finally, for a potential alternative in the future, keep your eye on the WordPress Playground project. That project aims to get WordPress working in the browser using WASM. There’s a demo available if you want to see it in action.

References

• wp-env NPM package
• wp-env in the Block Editor handbook
• wp-env for Gutenberg contributors
• wp-env package on GitHub

Props to @greenshady, @juanmaguitar, @welcher, @bph, @marybaum, @isabel_brison, and @webcommsat for reviewing this post and making suggestions that immeasurably improved it.