drupal-canvas-dev

An opinionated development environment for brewing Drupal Canvas, built with DDEV. I maintain this project to use for my day-to-day development work, with workflows and tools I prefer.

Setup

1. Clone the repository
2. Copy .ddev/.env.example to .ddev/.env
   1. Add your OpenAI API key to be used by the Canvas AI module
3. Run:

   ddev start \
     && ddev clone-repo \
     && ddev clone-repo-mercury \
     && ddev composer install \
     && ddev site-install \
     && ddev launch \
     && ddev ui --install
   

Agent setup

This project uses two agent configuration scopes:

• Environment scope for root-level tooling and infrastructure tasks.
• Canvas scope for module code work in web/modules/contrib/canvas.

For details on workspace entrypoints and skill locations, see agents/README.md.

Running ddev clone-repo also wires the Canvas agent files in the nested repository by creating symlinks for AGENTS.md and .agents/skills, and by adding local-only nested-repo excludes for AGENTS.md and .agents/ in .git/info/exclude.

Commands

Command	Description
n	Run npm inside the UI directory. --canvas-dir=<directory>: runs npm inside specified directory (root, ui, astro, cli, or docs)
ui	Build the UI code and start the dev server. --install -i: runs npm install before --skip-build -s: skips the build step
playwright	Run Playwright in UI mode. (Accessible via VNC at https://canvas.ddev.site:6081/vnc.html) --spec <path-to-spec>: runs a spec in headless mode
cy, cypress	Run the Cypress UI in end-to-end testing mode (Accessible via VNC at https://canvas.ddev.site:6081/vnc.html) --spec <path-to-spec>: runs a spec in headless mode --component -c: use component testing mode
phpunit [path]	Run PHPUnit tests in the module's codebase [path]: narrows to the path, relative to the module directory
phpcs [path]	Run PHP Code Beautifier and Fixer in the module's codebase [path]: narrows to the path, relative to the module directory
phpstan	Run PHPStan in the module's codebase
si, site-install	Install Drupal site, install and configure modules: Canvas, Canvas AI, Canvas OAuth. --ui: also installs Canvas Vite for UI development
clone-repo	Clone the Canvas module's repository, add local nested-repo excludes for AGENTS.md and .agents/, and set symlinks for AGENTS.md and .agents/skills. (Runs on the host.)
clone-repo-mercury	Clone the Mercury theme's repository. (Runs on the host.)

See the list of commands provided by DDEV out-of-the box.

Credits

My work on Drupal Canvas is made possible by Acquia.