Drupal Ddev
Configure and standardize local Drupal stacks with DDEV so you can develop and test without fighting PHP, database, and webserver versions.
Overview
Drupal DDEV is an agent skill most often used in Build (also Validate, Operate) that documents complete DDEV config.yaml settings for local Drupal 9–11 development.
Install
npx skills add https://github.com/grasmash/drupal-claude-skills --skill drupal-ddevWhat is this skill?
- Full .ddev/config.yaml reference with Drupal 9/10/11 project types
- Covers PHP 8.1+, MariaDB versions, nginx-fpm, Composer, and Node toolchains
- Documents hooks (e.g. post-start drush cr), upload_dirs, and web_environment vars
- Includes performance_mode (mutagen), router ports, and additional hostnames/FQDNs
- Explains naming, docroot (web), and omit_containers / additional_services patterns
- Documents drupal9, drupal10, and drupal11 DDEV project types
- Example stack includes PHP 8.3, MariaDB 10.6, nginx-fpm, Node 20
Adoption & trust: 1 installs on skills.sh; 67 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
Your Drupal local setup drifts across PHP, database, and docroot settings and breaks parity with how you deploy.
Who is it for?
Solo Drupal maintainers standardizing ddev config for drupal10/drupal11 projects on one machine.
Skip if: Teams on non-DDEV stacks only (Lando-only, pure Docker Compose without DDEV) or frontend-only Jamstack sites with no PHP docroot.
When should I use this skill?
You are creating, migrating, or reviewing a Drupal project’s DDEV configuration.
What do I get? / Deliverables
You get a validated .ddev/config.yaml pattern—hooks, env vars, and versions included—so ddev start yields a consistent Drupal backend you can build and debug against.
- .ddev/config.yaml snippets or full reference-aligned config
- Hook and environment variable recommendations
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Local Drupal runtime configuration is canonical on Build → backend because the primary artifact is a reproducible dev environment for the CMS codebase. Backend subphase matches docroot, PHP, MariaDB, and nginx-fpm settings—the core server-side contract for Drupal 9–11 projects.
Where it fits
Spin up drupal10 with docroot web and MariaDB 10.6 to demo a client theme before committing to hosting.
Audit PHP 8.3 and composer_version 2 in config.yaml before adding a custom module.
Set web_environment and additional_fqdns so a local OAuth callback matches your integration tests.
Align timezone and upload_dirs with production when reproducing a file-sync bug on ddev.
How it compares
Reference skill for DDEV YAML—not a replacement for Drupal module development or production hosting runbooks.
Common Questions / FAQ
Who is drupal-ddev for?
Solo builders and small teams shipping Drupal sites who want agent help drafting or reviewing DDEV configuration without reading the entire upstream docs each time.
When should I use drupal-ddev?
When scoping a Validate prototype, wiring Build backend containers, or tuning Operate-local parity (hooks, env, DB version) before debugging deployment mismatches.
Is drupal-ddev safe to install?
Check the Security Audits panel on this Prism page; the skill is documentation-heavy—review any suggested web_environment secrets and never commit production credentials into config.yaml.
SKILL.md
READMESKILL.md - Drupal Ddev
# .ddev/config.yaml Reference Complete reference for DDEV configuration file. --- ## Complete Example ```yaml name: myproject type: drupal10 docroot: web php_version: "8.3" webserver_type: nginx-fpm xdebug_enabled: false additional_hostnames: [] additional_fqdns: [] database: type: mariadb version: "10.6" nodejs_version: "20" composer_version: "2" router_http_port: "80" router_https_port: "443" web_environment: - ENVIRONMENT=dev - CUSTOM_VAR=value upload_dirs: - web/sites/default/files performance_mode: mutagen # macOS only nfs_mount_enabled: false use_dns_when_possible: true timezone: America/New_York omit_containers: [] additional_services: [] override_config: false provider: default hooks: post-start: - exec: drush cr ``` --- ## Core Settings ### Project Name ```yaml name: myproject ``` - Must be unique across all DDEV projects on machine - Used for container names and URLs - Convention: match directory name ### Project Type ```yaml type: drupal10 # Or drupal9, drupal11 ``` **Available Drupal types**: - `drupal10` - Drupal 10 (recommended) - `drupal9` - Drupal 9 - `drupal` - Auto-detect Drupal version - `drupal11` - Drupal 11 (when available) ### Document Root ```yaml docroot: web # Or docroot, public_html, or "" ``` - Relative to project root - Empty string `""` means project root - Standard: `web` for modern Drupal --- ## PHP Configuration ### PHP Version ```yaml php_version: "8.3" ``` **Drupal requirements**: - Drupal 10: PHP 8.1, 8.2, or 8.3 - Drupal 9: PHP 7.4, 8.0, 8.1, or 8.2 - Drupal 11: PHP 8.3+ ### Web Server ```yaml webserver_type: nginx-fpm # Or apache-fpm ``` **Options**: - `nginx-fpm` (recommended, faster) - `apache-fpm` (for .htaccess compatibility) --- ## Database Configuration ```yaml database: type: mariadb # Or mysql, postgres version: "10.6" # MariaDB: 5.5, 10.4, 10.6, 10.11 ``` **MariaDB versions**: - `10.6` - Recommended for Drupal 10/11 - `10.4` - Legacy, still supported - `10.11` - Latest **PostgreSQL** (less common for Drupal): ```yaml database: type: postgres version: "14" ``` --- ## Node.js ```yaml nodejs_version: "20" # 18, 20, 21, etc. ``` Used for: - Theme compilation (Gulp, Webpack) - Frontend tooling - Build processes --- ## Performance Settings ### Mutagen (macOS Performance Boost) ```yaml performance_mode: mutagen ``` **Benefits**: - 5-10x faster file operations on macOS - Two-way sync between host and container - Dramatically improves page load times **Trade-off**: - Small delay in file sync (~100ms) - Slight memory overhead ### NFS Mount (Alternative) ```yaml nfs_mount_enabled: true ``` **When to use**: - macOS performance issues - Alternative to mutagen - Requires NFS server setup --- ## Xdebug ```yaml xdebug_enabled: false # Change to true to enable by default ``` **Better approach**: Enable on demand ```bash ddev xdebug on # Enable when needed ddev xdebug off # Disable for better performance ``` --- ## Additional Hostnames ```yaml additional_hostnames: - api - admin ``` Creates: - `api.myproject.ddev.site` - `admin.myproject.ddev.site` **Use case**: Multi-domain or subdomain testing --- ## Additional FQDNs ```yaml additional_fqdns: - example.local - test.example.com ``` Fully-qualified domain names for testing specific domains. **Requires hosts file entry**: ``` 127.0.0.1 example.local test.example.com ``` --- ## Upload Directories ```yaml upload_dirs: - web/sites/default/files - web/sites/default/private ``` Directories synced with `ddev import-files` --- ## Environment Variables ```yaml web_environment: - ENVIRONMENT=dev - DRUPAL_ENV=local - CUSTOM_KEY=value ``` Available in PHP as `$_ENV['ENVIRONMENT']` --- ## Composer Version ```yaml composer_version: "2" # Or "1", "" ``` - `"2"` - Composer 2 (recommended) - `"1"` - Composer 1 (legacy) - `""` - Latest stable --- ## Custom Ports ```yaml router_http_port: "80" router_https_port: "443" ``` Change if port