Canvas Headless:
experience composition

Getting Started with Drupal Canvas Headless: Modern Experience Composition & Visual Editing

Keynote Recap & Tutorial
Based on the official unveiling of Drupal Canvas Headless at DrupalCon. Learn how to bridge enterprise decoupled frontends with real-time, in-context visual site editing.

1. Executive Summary & Architecture

Modern organizations must synthesize content, digital commerce, customer data, and microservices across disparate backends. Historically, choosing a decoupled ("headless") frontend meant sacrificing the intuitive in-context visual editing experience that marketers and content editors rely on.

Drupal Canvas Headless eliminates this compromise through Experience Composition:

• For Developers: Complete freedom to build using modern JavaScript/TypeScript meta-frameworks (Next.js, Astro, Nuxt, or TanStack Start).
• For Content Creators & Editors: A full WYSIWYG visual builder experience with real-time live preview of actual production components, theme styling, and immediate state updates.

Conceptual Architecture

   ┌────────────────────────────────────────────────────────┐
   │                  BACKEND ECOSYSTEM                     │
   │  ┌──────────────┐   ┌──────────────┐   ┌────────────┐  │
   │  │   Content    │   │   Commerce   │   │ Micro-     │  │
   │  │ (Drupal CMS) │   │ (Shopify/etc)│   │  services  │  │
   │  └───────┬──────┘   └──────┬───────┘   └─────┬──────┘  │
   └──────────┼─────────────────┼─────────────────┼─────────┘
              │                 │                 │
              ▼                 ▼                 ▼
   ┌────────────────────────────────────────────────────────┐
   │                 DRUPAL CANVAS ENGINE                   │
   │  • Unified Experience Composition                      │
   │  • Bidirectional State Sync & Component Schemas        │
   │  • Visual Builder & Publishing Governance              │
   └──────────────────────────┬─────────────────────────────┘
                              │
                    Live Preview & Schema
                              │
                              ▼
   ┌────────────────────────────────────────────────────────┐
   │                   HEADLESS FRONTENDS                   │
   │  ┌───────────┐   ┌───────────┐   ┌────────┐   ┌───────┐│
   │  │  Next.js  │   │   Astro   │   │  Nuxt  │   │Tan-   ││
   │  │           │   │           │   │        │   │Stack  ││
   │  └───────────┘   └───────────┘   └────────┘   └───────┘│
   └────────────────────────────────────────────────────────┘

2. Prerequisites

Before starting, ensure your environment meets the following specifications:

1. Drupal Instance with Canvas Enabled: A local or remote Drupal environment running the Drupal Canvas module (e.g., hosted via DDEV at https://canvas-env.ddev.site).
2. Node.js Runtime: Node.js v18.17+ or v20+.
3. Package Manager: pnpm (recommended), npm, yarn, or bun.

3. Step-by-Step Implementation Guide

+-----------------------------------------------------------------------------------+
| PIPELINE OVERVIEW:                                                                |
| [1. Navigate UI] ➔ [2. Scaffold Codebase] ➔ [3. Connect URL] ➔ [4. Live Visual]  |
+-----------------------------------------------------------------------------------+

Step 1: Access the Headless Frontends Manager

1. Open your Drupal Canvas environment (e.g., https://canvas-env.ddev.site).
2. In the Canvas primary navigation bar on the left, click on the Headless frontends icon (<*> / network node icon).
3. This opens the Headless frontends control center.

   View source diagram

   +-------------------------------------------------------------------------+
   | Drupal Canvas                                                           |
   +-------------------------------------------------------------------------+
   | [≡]                                                                     |
   | [+]                                                                     |
   | [↶]                                                                     |
   | [</>]                                                                   |
   | [📋]                                                                    |
   | [*]  <-- Headless frontends                                             |
   |                                                                         |
   |            Headless frontends                                           |
   |            Connect the frontend apps that render your Canvas content.   |
   |                                                                         |
   |            [ + Add frontend ]                                           |
   +-------------------------------------------------------------------------+

Step 2: Scaffold Your Headless Codebase

Drupal Canvas provides ready-to-run starter templates pre-configured with the Canvas bidirectional bridge.

1. Choose Your Framework & Package Manager

Under Set up your codebase, select your preferred options:

• Framework: Next.js | Astro | Nuxt | TanStack Start
• Package Manager: pnpm | npm | yarn | bun

2. Execute the Scaffolding Command

Run the generated command in your terminal. For example, using pnpm with the Astro template:

pnpm dlx @drupal-canvas/create@latest \
  --site-url https://canvas-env.ddev.site \
  --site-name "My Canvas Headless Project" \
  --template astro

(Alternative package manager variations:)

# npm
npx @drupal-canvas/create@latest --site-url https://canvas-env.ddev.site --site-name "My Canvas Headless Project"

# yarn
yarn dlx @drupal-canvas/create@latest --site-url https://canvas-env.ddev.site --site-name "My Canvas Headless Project"

# bun
bunx @drupal-canvas/create@latest --site-url https://canvas-env.ddev.site --site-name "My Canvas Headless Project"

3. CLI Prompts & AI Coding Agent Integration

During scaffolding, the CLI wizard configures developer tooling and prompts for modern AI tooling compatibility:

~/Projects
❯ pnpm dlx @drupal-canvas/create@latest \
  > --site-url https://canvas-env.ddev.site \
  > --site-name "My Canvas Headless Project" \
  > --template astro

Drupal Canvas  create

◆  Enter the project name
│  my-canvas-headless-project
│
◇  Fetching template...
│
◆  Which AI coding agents should this codebase support?
│  [x] Claude Code  (.claude/skills)
│  [x] Cursor       (.cursor/rules)
│  [x] AiderDesk
│  [ ] Augment
│  [ ] Zed / Warp
│
◇  Selected agents already use .agents/skills. No compatibility symlinks needed.
◇  Installing dependencies with pnpm...
✔  Scaffolding complete!

4. Start the Frontend Development Server

cd my-canvas-headless-project
pnpm run dev

By default, the server will spin up on http://localhost:3000.

Step 3: Connect and Register the Frontend

1. Return to the Headless frontends panel in Drupal Canvas.
2. Click the + Add frontend button.
3. Enter the URL where your frontend is serving traffic (local or remote):
   • Frontend URL: http://localhost:3000
4. Click Add frontend.

   View source diagram

   ┌─────────────────────────────────────────────────────────────┐
   │  Add frontend                                               │
   │  Enter the URL where your frontend app runs. This can be    │
   │  a local development server or a deployed environment.      │
   │                                                             │
   │  Frontend URL                                               │
   │  ┌───────────────────────────────────────────────────────┐  │
   │  │ http://localhost:3000                                 │  │
   │  └───────────────────────────────────────────────────────┘  │
   │                                                             │
   │                         [ Cancel ]   [ Add frontend ]       │
   └─────────────────────────────────────────────────────────────┘

Automatic Component Discovery

Once connected, the status badge turns green (● Ready). Canvas performs automated component introspection:

Activity Center
✔ Component sync completed
  Created 19, updated 0, and left 0 unchanged.

Step 4: In-Context Visual Editing & Real-Time Sync

1. Open your site page in Drupal Canvas editor.
2. The central viewport renders your actual decoupled application (e.g., the Elsewhere travel experience site).
3. The left panel provides your synced Component Library:
   • Hero
   • Card Grid
   • CTA Bar
   • Feature Matrix
   • Testimonial Slider
   • Image with Caption

     View source diagram

     ┌─────────────────┬───────────────────────────────────┬──────────────────┐
     │ COMPONENT TREE  │ LIVE RENDERED PREVIEW             │ INSPECTOR PANEL  │
     ├─────────────────┼───────────────────────────────────┼──────────────────┤
     │ ▾ Canvas Pages  │  Elsewhere    Journeys Our Story  │ Hero Component   │
     │   ▾ Home        │  ───────────────────────────────  │                  │
     │     • Header    │  A LITTLE FURTHER, A LITTLE SLOWER│ Button Label:    │
     │     • Hero      │  Find a little                    │ [Explore Journeys]│
     │     • Grid      │  more elsewhere.                  │                  │
     │     • Footer    │                                   │ Background:      │
     │                 │  [Explore our journeys]           │ [ Forest       ▼]│
     │                 │                                   │   Parchment      │
     │                 │                                   │   Ivory          │
     │                 │                                   │   Apricot        │
     │                 │                                   │ > Forest         │
     └─────────────────┴───────────────────────────────────┴──────────────────┘

Live Property Manipulation

• Select any component in the visual viewport or tree.
• In the right-hand Inspector Panel, adjust attributes (e.g., change Background color from Parchment to Forest).
• Result: The decoupled frontend hot-reloads the state change over the Canvas postMessage/WebSocket channel with zero lag, without triggering full-page refreshes.

Step 5: Review and Publish Workflow

Canvas separates draft staging from production deployments:

1. As you edit, changes are flagged in the top bar: Review 1 Change.
2. Click Review Changes to open the staged changes modal:
   • Review modifications (e.g., Home modified a moment ago).
   • Toggle specific page checkboxes to selectively bundle changes.
3. Click Publish Selected.
4. Visit your standalone frontend URL (e.g., http://localhost:3001 or your production domain). Your changes are live instantly!

4. Supported Framework Matrix

5. Developer & Editor Summary

6. Next Steps & Resources

• Scaffold a test project: pnpm dlx @drupal-canvas/create@latest
• Configure custom design tokens in your frontend’s Tailwind / CSS modules configuration.
• Bind external commerce APIs alongside Drupal content nodes inside custom Canvas component slots.