Craftcms-claude-skills ddev

DDEV local development environment for Craft CMS projects. ALWAYS load this skill when running any ddev command, configuring .ddev/config.yaml, or troubleshooting local container issues. Covers: config.yaml settings (project type, PHP/Node versions, database, docroot), shorthand commands (ddev composer, ddev craft, ddev npm), add-ons (ddev add-on get for Redis, Mailpit), custom commands (.ddev/commands/), Vite dev server exposure (web_extra_exposed_ports, web_extra_daemons), database import/export (ddev import-db, ddev export-db, ddev craft db/backup), Xdebug toggling (ddev xdebug on/off), sharing local sites (ddev share, temporary public URLs), and troubleshooting (ddev poweroff, ddev logs, ddev describe, ddev delete, port conflicts, container restart issues). Triggers on: ddev start/stop/restart, ddev craft, ddev composer, ddev npm, ddev ssh, ddev import-db, ddev export-db, ddev xdebug, ddev share, ddev add-on, ddev poweroff, ddev describe, ddev logs, .ddev/config.yaml, web_extra_exposed_ports, web_extra_daemons, PHP version or Node version in local dev, database backup/restore locally, ran npm/composer on host instead of ddev, wrong node_modules architecture, local dev environment for Craft CMS. NOT for production deployment, CI/CD pipelines, GitHub Actions, or server configuration. NOT for Docker/container usage outside of DDEV.

install

source · Clone the upstream repo

git clone https://github.com/michtio/craftcms-claude-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/michtio/craftcms-claude-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/ddev" ~/.claude/skills/michtio-craftcms-claude-skills-ddev && rm -rf "$T"

manifest: skills/ddev/SKILL.md

source content

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.

Shorthand Commands

Always use DDEV shorthand over

ddev exec

ddev composer install          # not ddev exec composer install
ddev craft up                  # not ddev exec php craft up
ddev npm install               # not ddev exec npm install
ddev craft make service        # scaffolding

Craft CMS Project Type

# .ddev/config.yaml
name: my-craft-site
type: craftcms
docroot: web
php_version: "8.3"
database:
  type: mysql
  version: "8.0"
nodejs_version: "20"

DDEV auto-injects:

CRAFT_DB_SERVER

CRAFT_DB_USER

CRAFT_DB_PASSWORD

CRAFT_DB_DATABASE

PRIMARY_SITE_URL

Common Commands

ddev start                     # Start the project
ddev stop                      # Stop the project
ddev restart                   # Restart containers
ddev ssh                       # SSH into web container
ddev describe                  # Show project info and URLs
ddev logs                      # View container logs
ddev import-db --file=dump.sql # Import database
ddev export-db --file=dump.sql # Export database
ddev xdebug on                 # Enable Xdebug
ddev craft db/backup           # Craft database backup

Post-Install Auto-Run

Composer scripts auto-run

craft up

after install/update:

{
    "scripts": {
        "post-craft-update": [
            "@php craft install/check && php craft up --interactive=0 || exit 0"
        ],
        "post-update-cmd": "@post-craft-update",
        "post-install-cmd": "@post-craft-update"
    }
}

No need to manually run

ddev craft migrate/all

ddev craft project-config/apply

—

ddev craft up

does both, and it auto-runs after

ddev composer install/update

Add-ons

ddev add-on get ddev/ddev-redis       # Install Redis
ddev add-on get ddev/ddev-mailpit     # Install Mailpit
ddev add-on list                       # List installed add-ons
ddev add-on remove ddev/ddev-redis    # Remove add-on

Custom Commands

Place scripts in

.ddev/commands/web/

(container) or

.ddev/commands/host/

(host):

#!/usr/bin/env bash
## Description: Run ECS code style check
## Usage: check-cs
## Example: ddev check-cs

cd /var/www/html && composer check-cs

Note: omit

#ddev-generated

on custom commands you maintain — DDEV overwrites files with that comment during updates. Only add-on-managed commands should include it.

Troubleshooting

ddev poweroff                  # Stop all DDEV projects
ddev debug router              # Debug router configuration
ddev debug capabilities        # Check Docker capabilities
ddev delete --omit-snapshot    # Remove project without snapshot