What the Canvas Demos Do Not Show: Drupal Canvas From the Command Line

Most demos of Drupal Canvas show the same thing: a marketer drags components onto a page, edits text in place, and publishes without filing a ticket. That modern, React-based editor is impressive. It is also only half the story.

The other half lives in a terminal. Canvas ships with an open source, code-first toolchain that lets developers treat components, pages, templates, and brand settings as files in Git. With it, a page builder becomes something an enterprise team can put under code review and continuous integration (CI). Below, I walk through what the tools are, how to start with them, and why it matters that they are open while a competitor pitches a closed alternative.

When you need more than a UI

A visual editor is the right tool for building a landing page. It is the wrong tool for keeping 40 brand sites in sync, gating releases behind code review, or wiring a React design system into a CMS. Those jobs need repeatable, scriptable, version-controlled workflows. Common examples include:

• A corporate design system as the single source of truth. The central design team owns an approved React component library. Every site must use those components, with only approved props, fonts, and colors exposed to editors.
• Decoupled frontends. Your frontend team works in Astro, Next.js, Nuxt, TanStack Start, or Angular, but editors still want visual page building.
• One library, many sites. Multisite portfolios, franchises, and universities need to push the same components to dozens of sites, each with its own Brand Kit.
• Pages and templates promoted like code. Teams with development, staging, and production environments want pages and templates reviewed in pull requests and deployed by CI, not rebuilt by hand.
• Editor-built work in version control. When marketers build in the UI, you still want a history and a rollback point in Git.
• AI-assisted development. Coding agents can turn a Figma frame or a screenshot into working components, but only if they follow your project's conventions.
• Redesigns and migrations. Capturing reference pages and turning external images and documents into managed media is tedious by hand and quick from a script.

Editors still work in the UI in every one of these cases. What changes is that developers decide, in code, which components and brand values editors get to use.

What are Canvas CLI and Acquia Nebula?

The Canvas CLI is the bridge between a local codebase and a Drupal Canvas site. Acquia Nebula is the project template that makes that codebase productive, especially for teams working with AI coding agents. Both are open source.

Canvas CLI

Published on npm as @drupal-canvas/cli and licensed GPL-2.0-or-later, the CLI lets teams build and manage Canvas Code Components outside the browser editor, with the repository as the source of truth. Uploading JavaScript is the smallest part of what it does:

The idea that matters most is full-site-as-code. Pages, content templates, and page templates sync alongside components, so a whole site experience can be reviewed, versioned, and promoted between environments.

Acquia Nebula

Nebula is Acquia's MIT-licensed starter for Canvas projects, and it is the default template behind npx @drupal-canvas/create. It wraps the CLI with the tooling a team would otherwise assemble by hand:

• Canvas Workbench for previewing components locally
• ESLint, Prettier, Husky, and GitHub Actions to catch Canvas validation errors before anything is pushed
• 25 example components, including hero, card, header, footer, navigation, accordion, and search, as a starting design system
• 24 agent skills in the open agentskills.io format, plus AGENTS.md guidance, so tools such as Claude Code, Codex, Gemini CLI, GitHub Copilot, and Cursor build components to Canvas conventions

Nebula also detects when its target is an Acquia Source site and switches page publishing and menu setup to the Acquia Source Model Context Protocol (MCP) server.

Getting started with Canvas CLI

You need Node.js 22.19 or later (or 24.5 or later) and a Drupal site with Canvas and its canvas_oauth submodule enabled. The recommended starting point is the create command, which scaffolds a Nebula project with the CLI already wired in:

npx @drupal-canvas/create@latest my-canvas-project
cd my-canvas-project
npx canvas login --site-url https://your-site.example.com

Three files control how the project talks to Drupal:

• canvas.config.json (committed) sets where components, pages, and templates live, and which resources sync.
• canvas.brand-kit.json (optional, committed) defines fonts and a color map that become choices in the editor's picker.
• .env (never committed) holds CANVAS_SITE_URL and, for CI, client credentials or an access token.

Developers authenticate interactively with canvas login. Pipelines use OAuth client credentials, and every write command supports --yes for non-interactive runs. Day to day, you mostly run three commands: npm run dev to preview in Workbench, npx canvas validate to check your work, and npx canvas push to ship it.

Spinning up a headless frontend with Astro

Canvas does not force a choice between visual editing and a modern JavaScript framework. The Canvas Headless SDK provides adapters for Next.js, Nuxt, Astro, TanStack Start, React, and Angular, so editors keep the Canvas experience while pages render in your framework of choice. Here is what that looks like with Astro.

1. Scaffold the app. The Astro template wires the canvas() integration into astro.config.mjs and writes your site URL to .env:

npx @drupal-canvas/create@latest my-canvas-frontend \
  --template astro \
  --site-url https://your-site.example.com

Draft preview runs per request, so the project uses a server-side rendering (SSR) adapter (@astrojs/node). CANVAS_SITE_URL is the only configuration, and the frontend holds no client secret.

2. Start the dev server and check the Canvas route.

cd my-canvas-frontend
npm run dev
curl -i http://localhost:4321/api/canvas/components

A 401 Unauthorized response is the right answer. It means the route exists and refuses requests without a credential.

3. Register the frontend in Canvas. In the Canvas editor, open Headless frontends, click Add frontend, and enter http://localhost:4321. The row should show Ready.

4. Add a component.

npx canvas scaffold --name my-hero

Set a name and status: true in the new component.yml, reload the editor, and the component appears in the library. Editors can now drag it onto a page, and Astro renders the result.

Already have an Astro app? Install @drupal-canvas/headless and @drupal-canvas/headless-astro, add the integration to your config, and render Canvas pages from a catch-all route:

// astro.config.mjs
import node from '@astrojs/node';
import canvas from '@drupal-canvas/headless-astro/integration';
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [canvas()],
});
---
// src/pages/[...slug].astro
import CanvasComponentTree from '@drupal-canvas/headless-astro/CanvasComponentTree.astro';
import { fetchPage } from '@drupal-canvas/headless-astro';

const { slug } = Astro.params;
const path = `/${(slug ?? '').split('/').map(encodeURIComponent).join('/')}`;
const page = await fetchPage(Astro, path);

if (!page) {
  Astro.response.status = 404;
}
---

{page && <CanvasComponentTree tree={page.content} />}

Routes your app already owns keep rendering as before. Canvas takes over only the paths editors build. Full steps are in the Astro quickstart and Wire an app you already have.

Syncing a corporate design system into a coupled Drupal site

Headless gets the headlines, but this use case needs no decoupled architecture at all, and it is often the strongest business case. Your central design team already maintains an approved React component library. The goal is to let editors build Drupal-rendered pages with those components, and only those components, without anyone copying code by hand.

1. Add the design system as a dependency. In a Nebula project, install the corporate component package from your npm registry. The CLI bundles any installed npm package when it pushes.
2. Wrap each approved pattern as a Code Component. Run npx canvas scaffold --name <pattern> for each one, import the component from the package, and define the editable props and slots in component.yml. Editors see only what you expose.
3. Sync the brand. Put brand fonts and colors in canvas.brand-kit.json, so the editor's color and font pickers offer approved values. To restrict a color prop to specific colors, set up color folders in the Canvas UI.
4. Verify before you ship. Preview in Workbench, run npx canvas validate, and let the Nebula CI workflow gate merges.
5. Push. npx canvas push uploads the components, the vendor bundle, and the Brand Kit. Editors can now drag and drop pages built from the approved library.

Brand Kit fonts can come from Google, Bunny, Fontshare, Fontsource, npm, Adobe, or local files, and the color map becomes CSS custom properties in the editor. Push is safe by default: colors are not deleted unless you pass --prune-colors.

When the design system ships a new version, the upgrade is a dependency bump, a rebuild, and another push. Every page that uses those components picks up the change. Add the --site-url flag and client credentials in CI, and the same repo can push to every site in a portfolio, each with its own Brand Kit.

The loop also runs in reverse. npx canvas pull brings pages, templates, and colors that editors built in the UI back into Git. The repository stays the source of truth even when marketers do their best work in the visual editor, and every change has a history and a rollback point.

Ownership ends up where it belongs. The design team owns the components, and editors can build only with what that team approved.

How Canvas compares

Of course, Canvas isn’t the only solution available in this space. In addition to the wealth of open source approaches available, there’s been some discussion recently about a solution announced by a Drupal hosting competitor. Even though their business to date has been largely based on the popularity of open source content management solutions, they have chosen to launch a new proprietary page-building solution, pitched as an AI-native layer for composing pages from React components. While their new offering is still in beta, it’s worth looking at how it compares to Drupal Canvas, based on what we know today.

To be fair, a couple of its ideas are good. Bundling code, content, and design changes into one reviewable unit is useful, and so is real-time editing that includes AI agents. But a launch page is not a toolchain. Here is how the two approaches compare on what is publicly documented today:

Note: the cited data above is considered accurate based on the public information available at the time of writing

Features aside, the bigger question is who owns what you build. When you build on Canvas, your components are React code in your repository, your content lives in Drupal, and the tools that connect them are open source code anyone can read, fork, and improve. If you change hosts, everything comes with you.

A proprietary composition layer reverses that. Your editorial workflow, your page structures, and your agent integrations depend on one vendor's roadmap and one vendor's platform. Launch coverage describes the product as a layer that sits in front of WordPress or Drupal rather than replacing them. Canvas gets you to the same outcome while keeping the open platform you already chose.

Drupal has always been strongest when improvements flow back to everyone. Canvas, the CLI, Nebula, and the agent skills are built that way, and every team that uses them benefits from the work of every other team.

Start from the terminal

If your team has only seen the Canvas editor, try the CLI next. Canvas CLI makes components, pages, templates, and brand settings into code you can review, test, and promote. Acquia Nebula gives your team, and your AI agents, a working project from the first command.

Try It Now:

npx @drupal-canvas/create@latest

Explore the Canvas CLI on npm, the Nebula repository on GitHub, and the Acquia Source developer docs to go further.