Introduction

Drupal Canvas currently delivers experiences through Drupal's rendering pipeline. This milestone adds first-class headless support, so teams can build their frontend with a JavaScript framework while editors continue to compose pages, content templates, and global regions in Canvas without any change to their workflows.

The high-level goals:

• A JavaScript developer with no prior Drupal experience can go from zero to a rendered, editable headless page in minutes.
• The solution is agent-first: AI coding agents can scaffold, build, and maintain a headless frontend without custom configuration, because every layer — the component registry specification, the APIs, and the tooling — is published in structured formats that agents can consume directly.
• Frontend teams can own the presentation layer end to end, while content teams keep working in Canvas independently.
• Existing Canvas sites using Code Components can adopt a headless frontend without rebuilding their content or components.

The work is split into three areas: an SDK, a content delivery API, and live preview.

SDK

An npm package that makes Canvas content buildable-against from JavaScript frameworks:

• A component registration API with TypeScript types, so developers define components once and editors can place them on pages in Canvas.
• A publicly documented, versioned component registry specification that third parties can build against, in a structured format that is also consumable by AI tooling.
• A framework-agnostic core with a Next.js adapter first; additional framework adapters can follow without changes to the core.
• New commands in the existing Canvas CLI to scaffold a headless project and to register, validate, and list components.
• A routing API that resolves URL paths to content entities and component trees, honoring aliases, redirects, and access rules.

Content delivery

A purpose-built content delivery API for headless rendering. The core JSON:API module is a generic entity API that returns raw data that clients must assemble across multiple requests; this API returns render-ready responses instead:

• A single request returns a fully resolved page: component tree with props and slots, global regions, content template, and SEO metadata.
• A path-resolution endpoint maps any URL to the correct content, handling aliases, redirects, and access control with appropriate HTTP status codes.
• Response shape is controllable through include query parameters, with defaults that render a complete page without configuration.
• The API is versioned from the start, with a clear definition of breaking changes.
• Draft content is accessible through signed, time-limited preview tokens, and responses carry cache metadata for CDN integration.

Where possible, this builds on existing contributed modules, such as Custom Elements and Lupus Custom Elements Renderer, extending them where gaps exist.

Live preview

The bridge between the Canvas editor and the headless frontend, so editors are never working blind:

• The Canvas preview frame embeds the actual decoupled frontend, and reloads to reflect the current draft state as the editor makes changes, without publishing.
• Preview covers pages, content templates, and global regions.
• Clicking a component in the preview selects the corresponding component in the editor, via rendered output annotated with component instance UUIDs.
• Setup is minimal for developers: one function call and one or two environment variables, with localhost supported out of the box.
• Draft access uses signed, time-limited, site-scoped tokens.
• A debug overlay, available outside production, surfaces connection status and actionable error details.
• The editing experience is unchanged for content creators and site builders; only the rendering mechanism differs.

The text of this document was written with AI assistance.