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 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",
  "aliasBaseDir": "src",
  "outputDir": "dist",
  "globalCssPath": "./src/global.css"
}

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.
`aliasBaseDir`	`src`	Base directory for shared local imports that use `@/`.
`outputDir`	`dist`	CLI build output directory. Workbench does not use this option.
`globalCssPath`	`./src/components/global.css`	Global CSS entry used by the CLI and Workbench.

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 and global CSS from Canvas. It can also pull pages with --include-pages or CANVAS_INCLUDE_PAGES=true.

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, and syncs global CSS.

Pages are included with --include-pages or CANVAS_INCLUDE_PAGES=true. 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