Code Components - Workbench

Canvas Workbench is a local preview and development app for Drupal Canvas Code Components inspired by Storybook. It scans your codebase, lists discovered components, pages, and content templates, and renders previews in an isolated frame.

Workbench has no required configuration. If your project uses the default Canvas layout, you can run it from your project root:

npx @drupal-canvas/workbench@latest

Installation

Install Workbench:

npm install @drupal-canvas/workbench

Then run it from your project root:

npx canvas-workbench

Configuration

Workbench can run without a canvas.config.json file, but it is useful to add one when your project does not use the default Canvas paths, or when you want Workbench to match your CLI setup.

Create canvas.config.json in your project root and set only the options you need:

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

Workbench reads these options:

Property	Default	Used for
componentDir	"src/components"	Root directory Workbench scans for component.yml, *.component.yml, source files, and mocks. The directory must be inside aliasBaseDir.
pagesDir	"./pages"	Directory Workbench scans for page specs such as pages/home.json.
contentTemplatesDir	"./content-templates"	Directory Workbench scans for content template specs such as content-templates/node.article.full.json.
regionsDir	"./regions"	Directory Workbench scans for global region specs such as regions/header.json.
layoutPath	"./src/layout.jsx"	Layout component wrapped around page and content template previews so global regions render around the output. If the file is absent, previews render without surrounding regions. See Workbench global regions.
aliasBaseDir	"src"	Base directory for resolving @/ imports inside component source files.
globalCssPath	"./src/components/global.css"	Global CSS entrypoint loaded into the preview iframe. This is where Workbench picks up shared styles and Tailwind setup.

If canvas.config.json is not present, Workbench uses those defaults. outputDir is part of the wider Canvas config surface, but Workbench does not use it.

What Workbench discovers

Workbench looks for the following files in your project:

• Component metadata: component.yml and *.component.yml
• Component source entries:
  • index components (component.yml): index.ts, index.tsx, index.js, or index.jsx
  • named components (*.component.yml): <name>.ts, <name>.tsx, <name>.js, or <name>.jsx
  • optional CSS entries: index.css or <name>.css
• Component mocks: mocks.json and *.mocks.json
• Page specs: pages/*.json
• Content template specs: content-templates/*.json
• Global region specs: regions/*.json

Workbench only discovers those files inside the configured componentDir, pagesDir, contentTemplatesDir, and regionsDir. Files elsewhere in the repository are ignored until you update canvas.config.json to point at that tree.

Component preview behavior

For each component, Workbench keeps a default preview that uses the first example value of every prop in component.yml.

When mock files are present, Workbench adds tabs in the preview panel:

• Default uses the first examples from component.yml
• Named mock tabs use the name value from each mock entry

This makes it easy to keep a quick default preview and add richer, scenario-specific previews side by side.

Next steps

To export standalone preview artifacts, see Code Components - Workbench preview build.

To add tabbed mock previews, see Code Components - Workbench mocks.

To add page specs for page previews, see Code Components - Workbench pages.

To add content template specs for entity previews, see Code Components - Workbench content templates.

To add global region specs for region previews, see Code Components - Workbench global regions.