Skip to main content

Local Environment

Onboarding to an ongoing or existing project means installing and setting up your local development environment with the packages and software you need to effectively begin working on tasks and feature updates. WDS uses Local as our primary local development tool, with DevContainers as an alternative for container-based workflows.

  • Local — primary local WordPress development tool for most projects
  • DevContainers — used for project builds and composer dependencies only

Importing a Site from Backup​

WDS has a shared Google Drive that contains (mostly) up-to-date copies of sites, either from others' local copies or the production/staging sites. If a backup is more than a few months old, check with your team lead to see if it needs to be refreshed.

All backups in the shared drive are set up for a one-drag install into Local. A backup .zip typically contains two parts: a local.sql database dump and a /files folder containing /wp-content. Local can natively import both as part of setup.

When creating the site in Local, confirm the PHP, server, and database options with your team lead — there may be project-specific requirements.

Project Clone and Bootstrap​

Once the Local import is finished, navigate to the site's working root and swap the imported /wp-content for the project repo:

rm -rf ./wp-content
git clone <repo url> ./wp-content

Then sync up fully with the origin:

git fetch

If the repo has multiple remotes:

git fetch --all

Running Build Scripts​

Most repos include a package.json, a composer.json, or both. Check these files for available build scripts before starting work. A common pattern is a top-level npm run build that iterates through project folders and runs both NPM and Composer installs.

Useful scripts to look for:

npm run build   # full build
npm run start   # start dev server
npm run dev     # dev mode (often includes a watch process)

Scripts with a watch parameter are particularly useful during development — they monitor for file changes and trigger rebuilds automatically.

Troubleshooting Builds​

Node / npm version mismatches — Verify you are on the correct Node version for the project. Some older projects use Node 14, 16, or 18, but most modern projects will use the Devcontainer. Adjust the below devcontainer.json to suit your project's needs.

PHP version mismatches — Local allows swapping PHP versions on the fly. If a build is failing, try adjusting the PHP version in Local settings and confirm the correct version with your team lead. Note that changing the PHP version in Local does not affect build dependencies — to switch PHP for build purposes, use link/unlink in Homebrew.

Lefthook errors — Some projects use Lefthook (lefthook.yml) to add Git hooks to the workflow. If you see Lefthook errors during a build, try switching your Node version.

DevContainer​

For projects using DevContainers, our standard configuration targets PHP 8.2 and Node 24:

{
	"name": "WDS BT",
	"image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
	"features": {
		"ghcr.io/devcontainers/features/php:1": {
			"version": "8.2",
			"installComposer": true,
			"installXdebug": false,
			"extensions": "tokenizer,xmlwriter,simplexml,dom,mbstring"
		},
		"ghcr.io/devcontainers/features/node:1": {
			"version": "24",
			"nodeGypDependencies": true,
			"installYarnUsingApt": false
		}
	},
	"customizations": {
		"vscode": {
			"extensions": [
				"bmewburn.vscode-intelephense-client",
				"dbaeumer.vscode-eslint",
				"esbenp.prettier-vscode",
				"stylelint.vscode-stylelint"
			]
		}
	},
	"postCreateCommand": "npm ci && composer install --no-interaction",
	"remoteUser": "vscode"
}

Owner: Mitch Canter | Last reviewed: 04-30-2026