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 and pages, 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": "./components",
  "pagesDir": "./pages",
  "aliasBaseDir": "src",
  "globalCssPath": "./src/components/global.css"
}

Workbench reads these options:

Property	Default	Used for
componentDir	process.cwd()	Root directory Workbench scans for component.yml, *.component.yml, source files, and mocks.
pagesDir	"./pages"	Directory Workbench scans for page specs such as pages/home.json.
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

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 add tabbed mock previews, see Code components - Workbench mocks.

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