Decoupling Drupal Canvas

Drupal Canvas is Drupal's modern page builder (docs). When paired with Lupus Decoupled, Canvas becomes a powerful decoupled page builder that supports varying frontend frameworks.

How It Works

Canvas pages are built from components in Drupal's Canvas editor. In this context, a component can be a custom element (a Vue/React component provided by the frontend) or a regular Drupal block — which can render any Drupal content, including Views blocks that themselves output custom elements. While editing, the editor renders live previews of components via JavaScript using a preview provider (i.e. the frontend). Once published, the page is served through the CE API like any other content (e.g. /ce-api/page/{id}), as regular custom elements API output, so components are regularly rendered by the frontend.

Drupal CMS

When using Lupus Decoupled Starter or a similar site template based upon Lupus Decoupled, you get a fully working setup with Canvas pre-configured. Refer to the Drupal CMS page for details.

Manual Setup

Apply the Lupus Decoupled Canvas Recipe to set up the module and its dependencies with a single recipe apply:

composer require drupal/lupus_decoupled_recipe_canvas
drush recipe ../recipes/lupus_decoupled_recipe_canvas

This installs and configures Canvas, Canvas ExtJS, and the Lupus Decoupled Canvas sub-module.

Configuring the Editor Theme

Configure the theme used for Canvas editor previews at /admin/config/system/lupus-decoupled/settings under "Lupus Decoupled theme". A minimal theme like Stark or Lupus Stark is recommended.

Providing Components

Components are provided via a component index: a JSON file listing available components, their props, and metadata. Canvas External JS Components (a Canvas extension for integrating external JavaScript components) reads this index and makes the components available in the Canvas editor UI.

• Vue/Nuxt: very well supported via nuxt-component-preview, see Component Previews
• React: no ready-made setup yet. fullfatthings/drupal-canvas-react provides a library for exposing React components and generating a component index, but some integration work is required to wire everything together.

For documentation on how to integrate other frontend frameworks, see Multi-Frontend.

Component Registration

Automatic Registration via Lupus CSR Themes

When a Lupus CSR-based theme is installed, components are automatically registered from the theme's bundled component-index. No manual steps are needed.

Automatic registration also works with a decoupled frontend when the lupus_decoupled_canvas module is installed, provided the configured frontend exposes a component index at the configured frontend base URL.

Decoupled Frontends

When using a decoupled frontend (e.g. a dev server), component registration must be triggered manually:

• UI: Go to Administration > Appearance > Components > External JS (/admin/appearance/component/extjs)
• Drush: drush canvas:extjs-auto-register
• Recipe config action: Use lupus_decoupled_canvas:registerComponents after configuring the preview provider URL

When the frontend base URL is changed via the Lupus Decoupled settings form, a prompt will remind you to update the component registration.

Relationship to Canvas Code Components

Drupal Canvas has built-in support for (P)React "code components" with their own bundler. These components are purely client-side rendered and currently do not integrate with Lupus Decoupled's CE API pipeline. Adding support for embedding them as custom elements would be straightforward, but is not implemented yet.