Skill

drupal-ddev

DDEV local development environment patterns for Drupal, including configuration, commands, database management, debugging tools, and performance optimization.

npx claudepluginhub ajv009/drupal-devkit

Tool Access

This skill uses the workspace's default tool permissions.

Preview

Comprehensive patterns for using DDEV as your local Drupal development environment, including setup, configuration, workflow optimization, and troubleshooting.

Supporting Assets

references/config-yaml.md

SKILL.md

Similar 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.

craftcms-claude-skills

typo3-ddev

Manages TYPO3 DDEV setups for extension development: generates backend/landing URLs, runs ddev commands (start/stop/exec/install), handles multi-version testing (v11-14), PHP/DB configs.

20 files

craft-workspace-webconsulting-skills

docker-local-dev

Generates Docker Compose and Dockerfile configurations for local development via interactive Q&A. Supports PHP/Laravel, WordPress, Drupal, Node.js, Python stacks with Nginx, Supervisor/PM2, databases, Redis, email testing.

20 files

devops-skills

Stats

Parent Repo Stars1

Parent Repo Forks0

Last CommitMar 22, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

DDEV for Drupal Development

Comprehensive patterns for using DDEV as your local Drupal development environment, including setup, configuration, workflow optimization, and troubleshooting.

When This Skill Activates

Activates when working with DDEV local development including:

DDEV configuration (.ddev/config.yaml)
Local environment setup and management
Database import/export operations
Drush integration
Xdebug and debugging tools
Performance optimization
Multi-site and custom commands

Available Topics

Core Setup

@references/installation.md - Installing and configuring DDEV
@references/config-yaml.md - .ddev/config.yaml reference
@references/commands.md - Essential DDEV commands

Database Operations

@references/database.md - Import, export, and snapshot workflows
@references/drush.md - Using Drush with DDEV

Development Tools

@references/xdebug.md - Debugging with Xdebug
@references/mailhog.md - Email testing with MailHog
@references/solr.md - Local Solr search setup

Advanced

@references/custom-commands.md - Creating project-specific commands
@references/hooks.md - Pre/post hooks automation
@references/performance.md - Optimizing DDEV performance
@references/multisite.md - Multi-site configuration

See /references/ directory for complete documentation.

Quick Reference

Essential Commands

# Start project
ddev start

# Stop project
ddev stop

# Restart services
ddev restart

# SSH into web container
ddev ssh

# Run Drush commands
ddev drush cr
ddev drush status
ddev drush config:status

# Run Composer
ddev composer require drupal/module_name
ddev composer update

# Database operations
ddev import-db --file=backup.sql.gz
ddev export-db --file=backup.sql.gz
ddev snapshot

# View logs
ddev logs
ddev logs -f    # Follow mode

# Describe project
ddev describe

# Access URLs
ddev launch     # Open site in browser

Basic .ddev/config.yaml

name: myproject
type: drupal10
docroot: web
php_version: "8.3"
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.6"
nodejs_version: "20"

# Additional services
additional_services:
  - solr

# Custom upload/execution limits
upload_dirs:
  - web/sites/default/files

# Performance settings
performance_mode: mutagen  # For macOS

Common Workflows

New Drupal Project

# Create project directory
mkdir myproject && cd myproject

# Initialize DDEV
ddev config --project-type=drupal10 --docroot=web --php-version=8.3

# Install Drupal via Composer
ddev composer create drupal/recommended-project

# Install Drush
ddev composer require drush/drush

# Start DDEV
ddev start

# Install Drupal
ddev drush site:install standard --site-name="My Site" --account-name=admin

# Launch site
ddev launch

Import Existing Project

# Clone repository
git clone repo-url myproject && cd myproject

# Start DDEV (reads .ddev/config.yaml)
ddev start

# Install dependencies
ddev composer install

# Import database
ddev import-db --file=path/to/backup.sql.gz

# Import files (if needed)
ddev import-files --source=/path/to/files

# Run updates
ddev drush updb -y
ddev drush cr

# Launch
ddev launch

Database Sync from Remote

# Get database backup from remote server
# Method 1: Via SSH and drush sql-dump
ssh user@remote.server "cd /path/to/drupal && drush sql-dump --gzip" > backup.sql.gz

# Method 2: Via platform-specific tools or download existing backup
# (depends on your hosting platform)

# Import to local DDEV
ddev import-db --file=backup.sql.gz

# Run updates
ddev drush updb -y
ddev drush cr

# Sanitize for local development (optional)
ddev drush sql-sanitize -y

Daily Development Workflow

# Morning: Start project
ddev start

# Pull latest code
git pull origin main

# Update dependencies if needed
ddev composer install

# Clear cache
ddev drush cr

# Work on features...

# Create database snapshot before testing
ddev snapshot --name=before-testing

# Test changes...

# If needed, restore snapshot
ddev snapshot restore --name=before-testing

# Evening: Stop project
ddev stop

Debugging with Xdebug

# Enable Xdebug
ddev xdebug on

# Run your debugger in IDE (PHPStorm, VSCode)
# Set breakpoints and refresh page

# Disable when done (improves performance)
ddev xdebug off

# Check Xdebug status
ddev xdebug status

VSCode launch.json:

{
  "name": "Listen for Xdebug",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/var/www/html": "${workspaceFolder}"
  }
}

Performance Optimization

macOS Performance (Mutagen)

# .ddev/config.yaml
performance_mode: mutagen

# Restart after config change
ddev restart

NFS Mount (Alternative for macOS)

# .ddev/config.yaml
nfs_mount_enabled: true

Database Tuning

# .ddev/config.yaml
database:
  type: mariadb
  version: "10.6"

# Create .ddev/mysql/my.cnf
[mysqld]
innodb_buffer_pool_size = 512M
innodb_log_file_size = 128M

Custom Commands

Create project-specific commands in .ddev/commands/web/:

Example: .ddev/commands/web/fresh-install

#!/bin/bash
## Description: Fresh Drupal install from scratch
## Usage: fresh-install
## Example: ddev fresh-install

set -e

echo "Installing fresh Drupal site..."

# Drop existing database
drush sql-drop -y

# Install Drupal
drush site:install standard \
  --site-name="My Site" \
  --account-name=admin \
  --account-pass=admin \
  -y

# Import config if exists
if [ -d /var/www/html/config/default ]; then
  drush config:import -y
fi

# Clear cache
drush cr

echo "Fresh install complete!"
echo "Login: admin / admin"

Make it executable:

chmod +x .ddev/commands/web/fresh-install
ddev fresh-install

Best Practices

Commit .ddev/config.yaml - Share config with team
Use ddev composer instead of local composer
Don't commit database snapshots - Too large
Create snapshots before risky operations
Disable Xdebug when not debugging - Performance impact
Use mutagen on macOS - Much faster file sync
Regular ddev poweroff - Free up system resources
Version pin services - PHP, database, Node.js
Use hooks for automation - Post-start tasks
Document custom commands - Help team members

Common Issues

Site Not Loading

# Restart project
ddev restart

# Check status
ddev describe

# View logs
ddev logs

# Clear Drupal cache
ddev drush cr

Database Connection Error

# Check database is running
ddev describe

# Verify settings.php or settings.ddev.php exists
ddev ssh
ls web/sites/default/settings*.php

Port Conflicts

# Stop all DDEV projects
ddev poweroff

# Check for port conflicts
lsof -i :80 -i :443

# Change router HTTP port if needed
ddev config --router-http-port=8080 --router-https-port=8443

Slow Performance on macOS

# Enable mutagen
ddev config --performance-mode=mutagen
ddev restart

# Or use NFS
ddev config --nfs-mount-enabled=true
ddev restart

Multi-Project Management

# List all projects
ddev list

# Stop all projects
ddev poweroff

# Remove stopped projects
ddev delete <project-name>

# Remove all project containers (keep files)
ddev delete --omit-snapshot --yes <project-name>

Related Skills

@drupal-config-mgmt - Config management workflows
@drupal-contrib-mgmt - Module management with Composer
@drupal-at-your-fingertips - General Drupal patterns

Official Documentation: https://ddev.readthedocs.io Drupal DDEV Quickstart: https://ddev.readthedocs.io/en/stable/users/quickstart/ Community Support: https://discord.gg/5wjP76mBJD