wp-env: Simple Local Environments for WordPress.

Local WordPress environments are now as simple as running a single command. wp-env is a zero config tool for painless local WordPress environments. It provides decisions over options so that users can quickly spin up WordPress without wasting time. Indeed, the goal is to make these environment easily accessible to all — whether you’re a developer, designer, manager, or anyone else. It really is this straightforward:

  1. From the directory of your WordPress source code, plugin, or theme, run wp-env start.
  2. Access the instance on localhost:8888. The local code is already mapped and ready for development!

In this basic example, there is no configuration. wp-env creates a Docker instance behind the scenes with the latest WordPress image and then maps the local theme or plugin to the environment as a Docker volume. This way, any changes you make to the code locally are reflected immediately in the WordPress instance.

wp-env requires both Docker and Node. Once these prerequisites are met, you can run npm install -g @wordpress/env to install wp-env locally. Feel free to test it out from the root of the Gutenberg repository!

For more advanced use cases, the experience is just as simple after one includes a short configuration file (called .wp-env.json) in the source code. Running wp-env start in the same directory as a .wp-env.json file will automatically start and configure everything for you according to the specifications in the file. This makes it easy for new folks to start contributing or testing in advanced environments without having to configure anything themselves.

The .wp-env.json file allows you to create fairly advanced local development setups. Here is the documentation for the config file, and below is an advanced use case:

{
  "core": "https://wordpress.org/wordpress-5.4-beta2.zip",
  "plugins": [
    "../../my-fancy-plugin/",
    "https://downloads.wordpress.org/plugin/classic-editor.1.5.zip",
    ".",
    "WordPress/gutenberg#master"
  ],
  "port": 1000,
  "testsPort": 1001,
  "config": {
    "WP_DEBUG_DISPLAY": true
  }
}

The core field allows us to specify a source for the core WordPress code. Additionally, the plugins and themes fields allow us to specify sources for plugins and themes. These sources can be in several formats: relative or absolute local paths, a GitHub repository, or a URL to a .zip file.

In the above example, we see the following:

  • The core field is mapped to a beta version of WordPress in the .zip format.
  • The plugins field contains several plugins. The first is a local path to a plugin, the next is a zip file, the third is the plugin in the same directory as the .wp-env.json file, and last is a reference to the master branch of the Gutenberg GitHub repository.
  • The port field overrides the port on which the instance is mounted. In this case, we access WordPress at http://localhost:1000.
  • The config field sets wp-config.php constants. Here, the WP_DEBUG_DISPLAY constant is set to true in the created WordPress instance.

You might need to create this file if your plugin or theme has a lot of dependencies or options required for development. Instead of offloading this configuration work to the consumer, .wp-env.json makes the development and testing of advanced setups easily accessible to anyone with wp-env installed.

Finally, props to @noisysocks and @epiqueras for making this tool possible. If you’d like to learn more about wp-env, see the documentation page, read the source code, or follow development progress. As always, feel free to open issues or pull requests on GitHub if you find bugs or have suggestions concerning the tool.

#wp-env