wp-env-local-dev
starsforks
How to install wp-env-local-dev?
lonsdale201/wp-agent-skills/wp-env-local-dev
$npx -y skills add Lonsdale201/wp-agent-skills --skill wp-env-local-devRun a local WordPress development environment with wp-env (the official @wordpress/env Docker wrapper) — the default choice for plugin and block development. Covers the npx @wordpress/env command (and the trap that bare "npx wp-env" installs an unrelated stub package), the .wp-en
SKILL.md
| 1 | # wp-env: the official local WordPress environment |
| 2 | |
| 3 | `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`. |
| 4 | |
| 5 | ## When to use this skill |
| 6 | |
| 7 | - Setting up a local WordPress for **plugin, theme, or block development**. |
| 8 | - A `.wp-env.json` / `.wp-env.override.json` exists in the repo or needs writing. |
| 9 | - The user asks for a "quick local WP", a WordPress sandbox, or Docker-based WP dev. |
| 10 | - Wiring PHPUnit against a real WP test suite (the tests instance ships it). |
| 11 | - Before hand-rolling docker-compose for WordPress — wp-env is the default; compose is the escape hatch. |
| 12 | |
| 13 | ## Prerequisites and the `npx wp-env` trap |
| 14 | |
| 15 | 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. |
| 16 | |
| 17 | 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: |
| 18 | |
| 19 | ```bash |
| 20 | npm install --save-dev @wordpress/env |
| 21 | npx wp-env start # now resolves to node_modules/.bin/wp-env — the real one |
| 22 | ``` |
| 23 | |
| 24 | ## Configure: `.wp-env.json` |
| 25 | |
| 26 | Committed to the plugin/theme repo root. A minimal, verified plugin-dev config: |
| 27 | |
| 28 | ```json |
| 29 | { |
| 30 | "core": null, |
| 31 | "phpVersion": "8.3", |
| 32 | "plugins": [ "." ], |
| 33 | "config": { |
| 34 | "WP_DEBUG": true, |
| 35 | "WP_DEBUG_LOG": true |
| 36 | } |
| 37 | } |
| 38 | ``` |
| 39 | |
| 40 | `"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. |
| 41 | |
| 42 | Key options: |
| 43 | |
| 44 | | Option | Default | Notes | |
| 45 | |---|---|---| |
| 46 | | `core` | `null` | `null` = **latest production WordPress** (verified: installs the current release even while the `wordpress` Docker image still lags behind). Accepts a version, GitHub ref, local path, or zip URL to pin. | |
| 47 | | `phpVersion` | `null` | e.g. `"8.3"` — verified the container really runs it. `null` = the WP default. | |
| 48 | | `plugins` / `themes` | `[]` | Paths, zips, or GitHub refs; all get installed, plugins get activated. | |
| 49 | | `mappings` | `{}` | Arbitrary host-path → container-path mounts (e.g. a mu-plugin or a second plugin). | |
| 50 | | `config` | WP debug defaults | wp-config constants as JSON pairs. | |
| 51 | | `port` / `testsPort` | `8888` / `8889` | Host ports of the two instances; `WP_ENV_PORT` env var overrides. | |
| 52 | | `multisite` | `false` | Multisite install. | |
| 53 | | `phpmyadmin` | `false` | Optional phpMyAdmin service. | |
| 54 | | `lifecycleScripts` | `{}` | Commands on `afterStart`, `afterClean`, etc. — e.g. activate extra config, import seed data. | |
| 55 | |
| 56 | `.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. |
| 57 | |
| 58 | An `env` key can override settings per instance (`env.development` / `env.tests`) — e.g. different plugins in the tests site. |
| 59 | |
| 60 | ## The t |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
