---
title: Code components - Workbench
description: Preview code components and page specs in a local UI.
---

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:

```bash
npx @drupal-canvas/workbench@latest
```

## Installation

Install Workbench:

```bash
npm install @drupal-canvas/workbench
```

Then run it from your project root:

```bash
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:

```json
{
  "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`

Workbench only discovers those files inside the configured `componentDir` and
`pagesDir`. 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](./preview-build/).

To add tabbed mock previews, see
[Code components - Workbench mocks](./mocks/).

To add page specs for page previews, see
[Code components - Workbench pages](./pages/).
