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, pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ repository, or a URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org to a .zip file.

In the above example, we see the following:

• The core field is mapped to a betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 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 branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". of the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/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