Wp Env Local Dev

wp-env: the official local WordPress environment

wp-env (@wordpress/env) is the WordPress project's own Docker wrapper — the same tool core and Gutenberg development uses. For plugin/block development it beats a hand-written docker-compose file: one JSON file maps your plugin in, you get a dev site and a separate tests site with the WP PHPUnit suite preinstalled, and Xdebug is a flag. This skill covers configuring and driving it; when you need custom services (Redis, Mailpit, nginx), that is where its abstraction ends — switch to wp-docker-compose-stack.

When to use this skill

• Setting up a local WordPress for plugin, theme, or block development.
• A .wp-env.json / .wp-env.override.json exists in the repo or needs writing.
• The user asks for a "quick local WP", a WordPress sandbox, or Docker-based WP dev.
• Wiring PHPUnit against a real WP test suite (the tests instance ships it).
• Before hand-rolling docker-compose for WordPress — wp-env is the default; compose is the escape hatch.

Prerequisites and the npx wp-env trap

Docker must be installed and running (Docker Desktop on macOS/Windows — WSL2 backend recommended on Windows — or Docker Engine on Linux), plus Node.js LTS.

Invoke it as npx @wordpress/env. Bare npx wp-env in a project that doesn't have @wordpress/env installed downloads an unrelated npm package named wp-env — a stub that just prints "Please run the command 'npx @wordpress/env' instead" (verified: it resolves to wp-env@1.0.1, not the WordPress tool). The short wp-env command is only safe once the real package is a dev dependency, because then the local bin wins:

npm install --save-dev @wordpress/env
npx wp-env start        # now resolves to node_modules/.bin/wp-env — the real one

Configure: .wp-env.json

Committed to the plugin/theme repo root. A minimal, verified plugin-dev config:

{
	"core": null,
	"phpVersion": "8.3",
	"plugins": [ "." ],
	"config": {
		"WP_DEBUG": true,
		"WP_DEBUG_LOG": true
	}
}

"plugins": [ "." ] mounts the current directory into wp-content/plugins/ and activates it — verified: the plugin shows active in wp plugin list and its hooks run on the frontend immediately; edits on the host are live, no sync step.

Key options:

.wp-env.override.json (gitignored) holds personal overrides: config and mappings merge, other keys (plugins, themes, core) replace — don't put one plugin in each file and expect both.

An env key can override settings per instance (env.development / env.tests) — e.g. different plugins in the tests site.

The twin instances

wp-env start boots two independent WordPress installs (verified, first boot ~2 min, restarts faster):

• Development — http://localhost:8888, login admin / password. Your daily site.
• Tests — http://localhost:8889, its own MySQL. This is what PHPUnit runs against, so test-suite DB wipes never touch your dev content.

Each has its own MySQL container; the DB ports are exposed on random host ports (printed by start) if a GUI client is needed, or set mysqlPort to pin one.

Daily commands

npx wp-env start              # boot / apply .wp-env.json changes
npx wp-env stop               # stop containers, keep everything
npx wp-env clean all          # reset the databases (dev, tests, or all)
npx wp-env destroy            # delete containers + volumes (asks; --force skips)

# wp-cli inside the containers — 'cli' targets dev, 'tests-cli' targets tests:
npx wp-env run cli wp plugin list
npx wp-env run cli wp user create editor editor@example.test --role=editor
npx wp-env run tests-cli wp option get siteurl        # → http://localhost:8889

# quote multi-arg commands as one string:
npx wp-env run cli "wp post create --post_type=page --post_title='Pricing'"

# run composer/phpunit from your plugin dir inside the container:
npx wp-env run cli --env-cwd=wp-content/plugins/my-plugin composer install

PHPUnit: the tests instance is pre-wired

The tests-cli container ships PHPUnit, Composer, and the WordPress PHPUnit test library — verified: WP_TESTS_DIR=/wordpress-phpunit is set and phpunit is on the PATH. This removes the whole install-wp-tests.sh + throwaway-DB dance:

npx wp-env run tests-cli --env-cwd=wp-content/plugins/my-plugin phpunit

Point your phpunit.xml bootstrap at getenv( 'WP_TESTS_DIR' ) and the suite runs against the tests instance's WordPress and database. For writing the tests themselves, and for the classic non-wp-env harness, see wp-phpunit-test-setup.

Xdebug

npx wp-env start --xdebug                 # mode: debug (step debugging)
npx wp-env start --xdebug=profile,trace   # other modes, comma-separated

Verified: the restarted container reports Xdebug loaded (3.5.3 at test time). Configure the IDE to listen on port 9003 with a path mapping from the wp-env WordPress sources to your local files. Without the flag, Xdebug is off — no need to "undo" it beyond a plain start.

Critical rules

• Use npx @wordpress/env, or install it as a dev dependency first — bare npx wp-env in a bare project pulls an unrelated stub package, not the tool.
• Docker must be running before any command — the errors when it isn't are cryptic (connection refused on the Docker socket), not self-explanatory.
• core: null tracks the latest production WordPress. Pin core when the plugin must be tested against a specific version; re-run start after changing .wp-env.json.
• Run PHPUnit against the tests instance (tests-cli), never the dev one — the suite resets the database it points at.
• .wp-env.override.json replaces plugins/themes wholesale — merge semantics only apply to config and mappings.
• destroy deletes volumes (content, uploads, DB). Use stop for day-to-day; clean to reset databases only.

Cross-references

• Run wp-docker-compose-stack when the project needs services wp-env doesn't model — Redis object cache, Mailpit, custom PHP extensions, nginx.
• Run wp-phpunit-test-setup for the PHPUnit harness details (polyfills, composer scripts, CI matrix) that apply on top of the tests instance.
• Run wp-phpcs-coding-standards — linting runs on the host, independent of wp-env; keep them separate concerns.

What this skill does NOT cover

• Custom multi-service stacks (Redis, SMTP capture, nginx, phpredis) — that's wp-docker-compose-stack.
• Production hosting or deployment of any kind — wp-env is a development tool only.
• WordPress Playground / wp-now (browser-WASM sandboxes) — fine for throwaway demos, different tool.

References

• wp-env documentation (canonical README): https://github.com/WordPress/gutenberg/tree/trunk/packages/env
• npm package: https://www.npmjs.com/package/@wordpress/env
• Block Editor Handbook — Getting started with wp-env: https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/