@wordpress/env: Allow temporarily overriding settings in .wp-env.json

[noisysocks]

It is useful while working on Gutenberg to run the development environment using a different setup to the one provided by default in Gutenberg's ~/.wp-env.json configuration.

Some examples:

• One may want to work on Core at the same time as Gutenberg by setting "core": "~/path/to/wordpress-develop/build".
• One may want to test their changes against the production version of WordPress by setting "core": null.
• One may want to test their changes against an older version of WordPress by setting "core": "WordPress/WordPress#5.2.0".
• One may want to configure their Gutenberg development environment to have some extra themes and plugins. For example, the gutenberg-starter-theme theme.

Here, I propose two approaches for accomplishing this. I think that we could implement one or both approaches.

Approach 1: Command line arguments

wp-env start could be modified to accept command line arguments that, if specified, override the associated values that are in .wp-env.json.

With this approach, you could start the development server using the latest production version of Gutenberg by running:

wp-env start --core null

Starting the development server with different plugins and themes would work similarly:

wp-env start --plugins . elliotcondon/acf --themes WordPress/gutenberg-starter-theme

Considerations:

• --core would accept a string, and --plugins and --themes would accept an array of strings.
• Specifying --core null will technically cause yargs to parse core as the literal string 'null'. We'll need to modify the source parser to treat 'null' as a special string literal which means null.
• These arguments should be only for overriding settings. That is, it should not be possible to run wp-env with these command line arguments in a directory that is not a WordPress installation, plugin or theme; or in a directory does not contain a .wp-env.json file.
• We will need to decide if --plugins and --themes overrides the setting in .wp-env.json or appends to the setting in .wp-env.json.

Approach 2: .wp-env.override.json

wp-env start could be modified to look for a file called .wp-env.override.json which, if it it exists, will be merged with the .wp-env.json file. This is similar to docker-compose.override.yml.

Gutenberg would then add .wp-env.override.json to its .gitignore file, meaning that developers can configure their environment exactly how they like it without worrying about stashing and re-stashing changes.

Fields in .wp-env.override.json would take precedence over fields in .wp-env.json using the same semantics as the object spread operator ({ ...config, ...overrides }).

That is, if one has the following .wp-env.json:

{
	"core": "WordPress/WordPress",
	"plugins": [ "." ]
}

And the following .wp-env.override.json:

{
	"plugins": [ "elliotcondon/acf" ]
}

The final configuration would be:

{
	"core": "WordPress/WordPress",
	"plugins": [ "elliotcondon/acf" ]
}

---

cc. @epiqueras @noahtallen

[epiqueras]

Looks good.

We will need to decide if --plugins and --themes overrides

Override is more flexible.

[epiqueras]

I don't think the first approach makes sense anymore, considering you would have to make sure you call future commands with the same parameters, and it could lead to some hard to support bugs and edge cases.

[noisysocks]

That's a good point. The amount of 'considerations' I listed in the description is a hint that it's probably not a good idea 🙂

.wp-env.override.json is clear, flexible and will address this use case.

[noahtallen]

Love it. Very useful feature 🎉