Code Components - Local codebase

The Canvas CLI is the command-line tool for working with local Canvas content. Use it when you want to manage Code Components with your own editor, source control, shared local code, static assets, SVGs, package dependencies, or component metadata files. It can also manage pages, content templates, global regions, and Brand Kit fonts.

The most important commands are push and pull.

See @drupal-canvas/cli on npm

Start a local codebase

The fastest way to start a local codebase is with @drupal-canvas/create.

npx @drupal-canvas/create@latest

Depending on the template, the generated project is generally ready to use with the Canvas CLI. The CLI supports the same component and package imports as the in-browser code editor, and also lets local codebases add shared files, static assets, SVG files, package dependencies, and local component.yml metadata.

Configure a local codebase

Use canvas.config.json in the project root when your local codebase does not use the default Canvas paths. You can set only the options you need.

{
  "componentDir": "src/code-components",
  "pagesDir": "pages",
  "contentTemplatesDir": "content-templates",
  "regionsDir": "regions",
  "layoutPath": "src/layout.jsx",
  "aliasBaseDir": "src",
  "outputDir": "dist",
  "globalCssPath": "src/global.css",
  "sync": {
    "pages": true,
    "contentTemplates": true,
    "regions": true
  }
}

Option	Default	Purpose
`componentDir`	`src/components`	Directory scanned for Code Components. The directory can have any name, but must be inside `aliasBaseDir`.
`pagesDir`	`pages`	Directory scanned for page definitions.
`contentTemplatesDir`	`content-templates`	Directory scanned for content template definitions.
`regionsDir`	`regions`	Directory scanned for global region definitions.
`layoutPath`	`src/layout.jsx`	Layout component used by Workbench to wrap page and content template previews so global regions render around them. The CLI does not use this option.
`aliasBaseDir`	`src`	Base directory for shared local imports that use `@/`.
`outputDir`	`dist`	CLI build output directory. Workbench does not use this option.
`globalCssPath`	`src/global.css`	Global CSS entry used by the CLI and Workbench.
`sync.pages`	`true`	Include pages in `canvas pull` and `canvas push`. Set to `false` to exclude pages by default.
`sync.contentTemplates`	`true`	Include content templates in `canvas pull` and `canvas push`. Set to `false` to exclude content templates by default.
`sync.regions`	`true`	Include global regions in `canvas pull` and `canvas push`. Set to `false` to exclude global regions by default.

For existing projects, if globalCssPath is not set and src/global.css is missing, Canvas temporarily falls back to src/components/global.css when that file exists. Move the file to src/global.css, or set globalCssPath explicitly to keep the legacy location.

The componentDir option controls where local tools discover Code Components. The directory can have any name, but it must be inside aliasBaseDir. Place each component directly inside componentDir instead of nesting component folders inside grouping folders.

import Card from '@/components/card';

The aliasBaseDir option controls shared local code imports. With the default aliasBaseDir of src, this import resolves from src/lib/formatDate.

import { formatDate } from '@/lib/formatDate';

Pull from Canvas

Use canvas pull to download Canvas content into a local codebase.

npx canvas pull

The command pulls Code Components, global CSS, pages, content templates, and global regions from Canvas by default. To exclude pages, content templates, or global regions by default, set sync.pages, sync.contentTemplates, or sync.regions to false in canvas.config.json. To exclude them for a single run, use --no-pages, --no-content-templates, or --no-regions.

Brand Kit fonts are included with --include-brand-kit or CANVAS_INCLUDE_BRAND_KIT=true. When Brand Kit sync is enabled, the command updates canvas.brand-kit.json and downloads font files into the local codebase. See Brand Kit.

Push to Canvas

Use canvas push to build and upload local Canvas content.

npx canvas push

The command discovers components in the local codebase, builds the browser assets, runs the Tailwind CSS build, uploads component configuration, syncs global CSS, and pushes pages, content templates, and global regions by default. To exclude pages, content templates, or global regions by default, set sync.pages, sync.contentTemplates, or sync.regions to false in canvas.config.json. To exclude them for a single run, use --no-pages, --no-content-templates, or --no-regions.

Brand Kit fonts are included with --include-brand-kit or CANVAS_INCLUDE_BRAND_KIT=true when canvas.brand-kit.json is present.

After Code Components are pushed, they can still be opened and edited in the in-browser code editor. New source files, static assets, SVGs, and package dependencies should continue to be added from the local codebase.

JavaScript tooling

These packages are commonly included in templates scaffolded with @drupal-canvas/create and support local Code Component development.

Package	Description
`@drupal-canvas/workbench`	Local preview and development app for Code Components. See Workbench.
`@drupal-canvas/eslint-config`	ESLint config for validating Code Components.

Agentic skills

The drupal-canvas/skills repository publishes skills for AI coding agents developing Code Components.

npx skills add drupal-canvas/skills