wp-env Development Environment – WordPress Plugin Boilerplate

The plugin uses @wordpress/env to provide a consistent, containerized WordPress development environment. This is useful for local development and CI/CD pipelines where a full WordPress installation is required.

After cloning the repository:

Terminal

composer install
npm ci
npm run build
npm run env:start

Note

WP-CLI is treated as an environment dependency. Commands such as composer run i18n:extract and composer run i18n:compile assume that wp and the required WP-CLI packages are already available in the active environment. If you run the commands outside wp-env, install WP-CLI yourself. See the official WP-CLI installation guide.

Configuration

See .wp-env.json for the configuration. The setup uses mappings instead of the common plugins: ["."] approach and runs the containers with PHP 8.1 so WP-CLI i18n commands support the make-php compilation step.

The test configuration prefers port 8889; locally, both configurations fall back to an available port.

Why mappings instead of plugins: ["."]

The standard approach maps the current directory as a plugin, but the resulting folder name depends on the parent directory name. This causes issues when:

• Different developers have different folder names for their checkout
• CI/CD environments use unpredictable directory names
• WP-CLI commands need to target the plugin by name

Using explicit mappings with a hardcoded plugin name ensures deterministic paths and reliable WP-CLI targeting across all environments.

Available Scripts

Scripts that interact with wp-env are defined in package.json:

Script	Description
npm run env:start	Start the Docker containers
npm run env:stop	Stop the Docker containers
npm run env:destroy	Remove containers and data
npm run env:cli	Run commands inside the container
npm run env:test:start	Start the isolated application-test environment
npm run env:test:stop	Stop the isolated application-test environment
npm run env:test:cli	Run commands inside the application-test environment
npm run test:php	Start the test environment and run PHPUnit application tests

Running Commands Inside wp-env

The env:cli script is pre-configured with the correct working directory:

Terminal

npm run env:cli -- composer run i18n:compile
npm run env:cli -- composer run phpstan

The afterStart hook only activates Demo Plugin.

Adding Custom Scripts

Host-side scripts (interacting with wp-env from outside) belong in package.json:

package.json

{
  "scripts": {
    "env:my-script": "wp-env run cli my-command"
  }
}

Container-side scripts (executed inside wp-env) belong in composer.json because Composer is available inside the container but npm is not:

composer.json

{
  "scripts": {
    "my-script": "wp some-command"
  }
}

Then run it with:

Terminal

npm run env:cli -- composer run my-script

Usage in CI/CD

The plugin uses wp-env in the deploy workflow to compile translations. This requires a full WordPress environment with WP-CLI available.

Things to Keep in Mind

• Docker must be installed and running
• Ports are selected automatically and may differ between starts
• The first start downloads WordPress core, so it may take a few minutes
• Data persists between starts unless you run env:destroy
• The afterStart lifecycle script automatically activates the plugin
• The PHP version is pinned to 8.1 because composer run i18n:compile uses wp i18n make-php