Create your own wp-env npm package

wp-env is a super nice tool to kickstart plugin and/or theme development. It is zero-config, which makes it very usefult for people who don’t like to mess around with Dockerfiles, manually downloading WP, basic configuration, setting up a DB, … So that’s almost everyone, right?

Well.. I don’t think so. While I do believe that beginning developers will find wp-env super duper useful, more seasoned developers often want to create their own tools.

In my case for example, I wanted to use a custom docker-image with xdebug pre-installed in the wordpress container. And I did so by creating my own bdwm-wp-env package.

Below I’ll explain how you can create and use your own my-wp-env package in 4 simple steps.

1. Copy the wp-env repository

The easiest way to do this is to clone the Gutenberg repo and then copy the packages/env folder to a convenient place.

git clone
cp gutenberg/packages/env ~/whatever/

2. Rename wp-env to my-wp-env

open the copied env folder in VS code and find replace the folowing:

  • Find: wp-env
  • Replace: my-wp-env
  • Find: @wordpress/env
  • Replace: @yourname/my-wp-env

3. Publish your package to npm

Maker sure you created an account on with the username yourname. Or create and org with the name yourname.

Also, make sure you are logged in to your terminal with the command:

npm adduser

Now simply publish your package to npm following this guide:

4. Use your package

Install your package globally with:

npm install -g @yourname/my-wp-env

After your package is published, go to the folder where you are developing your plugin or theme, and run

my-wp-env start

That’s it. You now have your own npm package that is a copy of wp-env. You can now start modifying the files in your my-wp-env folder and release updates to npm.

To start using your updated env, just run npm update -g my-wp-env.

The next time you want to open a project or a plugin or theme inside your custom environment, you just run my-wp-env start again, and you are running the project in your latest update of the environment.


You now have one place where you can manage your dev-env. This is much better than adding docker-compose, Dockerfiles and so on inside your projects. You are always copying the same stuff over and over, and the dev-env of projects from a year ago will look much different than the ones you create today. It’s so much better to DRY.