ddev

DDEV for Craft CMS Development

Companion Skills — Always Load Together

When this skill triggers, also load:

• craftcms — Plugin/module development. Required when DDEV commands involve Craft CLI (ddev craft make, ddev craft migrate, ddev craft project-config).
• craft-php-guidelines — PHP coding standards. Required when DDEV commands involve code quality tooling (ddev composer check-cs, ddev composer phpstan, ddev craft pest/test).

Documentation

• DDEV docs: https://docs.ddev.com/en/stable/
• Craft CMS quickstart: https://docs.ddev.com/en/stable/users/quickstart/#craft-cms
• Configuration reference: https://docs.ddev.com/en/stable/users/configuration/config/
• Custom commands: https://docs.ddev.com/en/stable/users/extend/custom-commands/
• Additional services: https://docs.ddev.com/en/stable/users/extend/additional-services/
• Vite integration: https://docs.ddev.com/en/stable/users/usage/developer-tools/#nodejs

When unsure about a DDEV feature, WebFetch the relevant docs page.

Common Pitfalls

• Using ddev exec composer install instead of ddev composer install — DDEV shorthand commands handle path resolution and environment setup. Always use the shorthand.
• Forgetting ddev craft up does both migrate/all and project-config/apply — no need to run them separately after pulls or deploys.
• Exposing the Vite dev server with ports instead of web_extra_exposed_ports — ports causes conflicts when running multiple DDEV projects. web_extra_exposed_ports routes through Traefik and works with HTTPS.
• Running ddev composer global require — global packages install inside the container and vanish on restart. Install project-level dependencies only.
• Setting nodejs_version but running npm install on the host — Node must run inside the container via ddev npm to match the configured version.
• Editing .ddev/config.yaml while containers are running without restarting — changes to config require ddev restart to take effect.
• Using ddev import-db without --target-db=db on multi-database setups — the default target is db, but if you've configured additional databases, be explicit.
• Adding #ddev-generated to custom commands you've customized — DDEV overwrites files with this comment during updates. Only use it for add-on-managed commands. Custom commands you maintain should omit it.
• Running composer install on the host then ddev composer check-cs/ddev composer phpstan — if the host PHP version differs from DDEV's (e.g., host PHP 8.4, DDEV PHP 8.3), vendor/composer/platform_check.php fails. Always run ddev composer install so vendor/ matches the container's PHP version.