Drupal Canvas CLI Integration Playbook

Classification: PROCEDURE. Not authority; the governing standard below owns the rules.
Authority: how-we-build §17
Tool: @drupal-canvas/cli (npx canvas)

---

1. Overview & Setup

Drupal Canvas components (React/Tailwind) and page templates are managed outside the browser using the official CLI.

Configuration (canvas.config.json)

{
  "pagesDir": "./pages",
  "regionsDir": "./regions",
  "contentTemplatesDir": "./content-templates",
  "componentDir": "web/themes/custom/contextcontrol_theme/components",
  "deprecatedComponentDir": "web/themes/custom/contextcontrol_theme/components"
}

---

2. Core CLI Commands

# 1. Pull latest components, pages, and regions from Drupal
npx canvas pull --include-regions --include-pages -y

# 2. Extract AI Agent Context (prop sources, view modes, expressions)
npx canvas agents-context --all

# 3. Validate components and auto-fix lint issues
npx canvas validate --fix

# 4. Reconcile external media references in templates
npx canvas reconcile-media --yes

# 5. Build Tailwind CSS and push to Drupal site
npx canvas push --include-regions --include-pages -y

---

3. Invariants

• Never edit compiled CSS or generated JavaScript in web/themes/ directly.
• Page and region assembly goes through @drupal-canvas/cli, never theme preprocess.
• Authentication tokens are stored in ~/.config/drupal-canvas/oauth.json via OAuth 2.0 PKCE.