Enable Canvas Headless

Goal: turn on Canvas Headless in a Drupal codebase you control, so the Drupal Canvas editor can render its preview through a frontend app you build.

What you’ll have when you’re done

• The canvas_headless submodule enabled, with the dependency stack it needs.
• Headless frontends in the Canvas editor’s icon rail, ready for a frontend app to register.

Prerequisites

• A Drupal codebase you control with Drupal Canvas 1.9.0 or later (drupal/canvas): Canvas Headless first shipped in 1.9.0, released 29 July 2026.
• Composer and Drush against that codebase. The commands below show a project managed with DDEV; elsewhere, drop the ddev prefix.

Steps

1. Add the dependencies and enable the module. canvas_headless ships inside Drupal Canvas as a submodule, off by default and hidden from the Extend screen. It declares custom_elements, lupus_ce_renderer, and lupus_decoupled_ce_api as dependencies. Two Composer projects supply all three, drupal/custom_elements and drupal/lupus_decoupled, the second bringing lupus_ce_renderer and lupus_decoupled_ce_api with it:

   ddev composer require drupal/custom_elements drupal/lupus_decoupled
   ddev drush en canvas_headless -y

   The following module(s) will be installed: canvas_headless, custom_elements, lupus_ce_renderer, metatag, token, lupus_decoupled_ce_api, trusted_redirect
   
    // Do you want to continue?: yes.
   
    [success] Module canvas_headless has been installed. (Permissions)
    [success] Module custom_elements has been installed.
    [success] Module lupus_ce_renderer has been installed.
    [success] Module metatag has been installed. (Permissions - Configure)
    [success] Module token has been installed.
    [success] Module lupus_decoupled_ce_api has been installed. (Permissions)
    [success] Module trusted_redirect has been installed. (Permissions)

2. Confirm it in Canvas. Open the Canvas editor: Headless frontends now sits in the icon rail down the left edge. Seeing it needs the Administer Canvas Headless frontends permission.

When something goes wrong

Unable to install modules: module 'canvas_headless' is missing its dependency module custom_elements.

drush en ran before the Composer step. The Composer line in step 1 is what makes the enable work; without it, drush en stops on the missing dependencies one at a time. Run the Composer requirement, then enable again.

Next steps

• Register a frontend app: Headless frontends takes the app’s URL, and the editor previews through the first Ready app in the list.
• Canvas CLI reference: pull and push the components a frontend serves.