# Enable Canvas Headless

**Goal:** turn on [Canvas Headless](/start-here/glossary/#canvas-headless) in a Drupal codebase you control, so the [Drupal Canvas](/start-here/glossary/#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](/start-here/glossary/#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](https://docs.ddev.com/en/stable/users/install/ddev-installation/); 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:

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

   ```text
   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](/source-cms/reference/canvas-cli/): pull and push the components a frontend serves.