TypeScript Workbench previews
A Workbench preview renders a component or page from your own source code,
in named scenarios, next to your design pages. You define it in a
.workbench.ts or .workbench.tsx file, with an adapter for HTML, React, Vue,
Astro, React Native Web, or a technology you register yourself.
Like a story in Storybook, a preview renders your real component or page, but not a running copy of your app. Each scenario supplies the data the page would load, through props, providers, or mocked requests, and Workbench keeps it on the canvas: its links open other previews, and everything else it would do on a real site, such as following a route, submitting a form, or starting a download, is recorded under Actions instead. See Preview data, mocks, and actions.
Workbench mounts your content into a container that fills the artboard width,
including with a flex body and loading, empty, or error content. Styles targeting
your production root, such as #app, do not target the preview mount; keep any
additional root styling in your preview source or environment.
This page covers what every preview shares: definitions, scenarios, controls, lifecycle hooks, the command-line tools, and portable exports. Each framework has its own guide:
| Adapter | Renders | Guide |
|---|---|---|
react |
A React component, with inputs as props |
React |
react-native-web |
A React Native component through React Native Web | React Native Web |
vue |
A Vue 3 single-file component or module, with inputs as props |
Vue |
astro |
An Astro component or page, rendered on the server | Astro |
html |
An HTML file with its styles and scripts, or a module that mounts into the canvas | HTML |
| Your own | Anything you can mount from a browser module | Custom adapters |
You need:
workbench.yamlat the project root.name: Acmealone is enough when previews supply every page.- A trusted workspace, since previews run project code.
- The framework you render with, installed in your project. Workbench compiles TypeScript, JSX, and Vue files itself, but uses your project’s React, Vue, Astro, or React Native Web. It never installs or replaces them.
Add a preview
-
Write a definition next to the component, such as
src/Button.workbench.ts:import { definePreview } from '@canonic2/workbench'; export default definePreview({ id: 'components/button', title: 'Components/Button', adapter: 'react', source: { entry: './Button.tsx', export: 'Button' }, inputs: { label: 'Continue', disabled: false }, controls: { label: { type: 'text' }, disabled: { type: 'boolean' }, }, scenarios: { default: {}, disabled: { inputs: { disabled: true } }, }, });Workbench supplies
@canonic2/workbenchwhen it compiles the file. For TypeScript and your editor, install it as a development dependency; see Types. This example renders a React component; each framework guide has a complete example of its own. -
Run Workbench: Refresh Pages, or save
workbench.yaml. The preview appears in the page list with its scenarios, and opens on the canvas like any other page.
Workbench finds every *.workbench.ts and *.workbench.tsx file in the
project. It skips hidden folders, node_modules, dist, build, and
coverage, and whatever your project’s .gitignore files ignore, such as
Rust’s target folder. To choose other files or turn previews off, see
Previews in the configuration reference.
The title places the preview in the sidebar. Its first segment names the
collection, its last the page, and any segments between them a group:
Components/Forms/Button is Button, in a Forms group, in the
Components collection. A title without / goes in a Previews
collection.
Without a title, the id is used.
Set icon: 'monitor' on definePreview for a page preview, or use
previews.icons in workbench.yaml to assign icons by title prefix. A
definition’s icon wins over the longest matching prefix, then previews.icon,
then the default component. Collection icons are configured separately; an
icon-only handwritten collection can style a collection shared with Storybook.
See preview icon settings and
collection precedence.
Collections and groups with exactly matching names are shared with your
hand-written pages. For example, a preview titled Web App/Pages/Jobs and a
hand-written page in the Pages group of the Web App collection appear
in one Pages group under Web App.
A file that fails to load or has an invalid definition is reported with the other configuration problems. The remaining previews still load.
To place a preview yourself, give a page in workbench.yaml the definition
as its src, such as src: src/Button.workbench.ts. The page keeps its place
and label, and takes its scenarios from the definition. The file must still match
the discovery patterns.
A .workbench.ts or .workbench.tsx file can also default-export
defineDocs({...}) from @canonic2/workbench instead of definePreview, to
declare a Markdown page:
Markdown with live examples and the docs lenses that render them. It is
discovered with the previews and placed by its title the same way, except
that a title without / goes in a Docs collection. If workbench.yaml also lists its Markdown
file, the listed page is used instead. To give a preview page its own docs,
set docs on its entry in workbench.yaml. See Docs.
Name the preview lens
To rename the preview’s own lens, set previews.lensLabel in workbench.yaml:
previews:
lensLabel: Design
This changes the default Preview label to Design for discovered
previews. An explicitly listed page can set its own lensLabel to override
that value. These are YAML settings, separate from the preview definition’s
title, which places and names the page in the sidebar. They rename the
existing lens without adding a second button. If a preview is used as a
kind: workbench implementation, set that implementation’s label instead.
See Customize lens labels.
Define a preview
| Key | Description |
|---|---|
id |
Required. Kebab-case segments separated by /, such as components/button. Unique in the project, across previews and docs pages. |
title |
Where the preview appears in the sidebar. Defaults to id. |
adapter |
Required. html, react, vue, astro, react-native-web, or a registered name. |
source |
Required. entry is the file to render, relative to the definition and inside the project. export names its export and defaults to default. |
inputs |
Data passed to the source: props for React and Vue, Astro.props for Astro. |
controls |
Inputs you can edit in Preview controls. See Controls. |
scenarios |
A map of kebab-case scenario IDs to scenarios. |
artboards |
An explicit map of artboards shown together within this page. Each has an optional label, integer width and height from 1 to 8192, and optional inputs. See Multiple artboards. |
links |
The addresses the source links or submits to, each mapped to the preview it opens. See Links and navigation. |
requests |
Answers to the page’s fetch and XMLHttpRequest calls. See Request mocks. |
sizes |
The artboard sizes the preview supports: any of fit, laptop, mobile, and resizable. See Sizes. |
docs |
Text shown under Documentation in Preview controls. |
fixtures, globals |
Data and settings that environments, hooks, and request handlers read from the context. See Fixtures and globals. |
styles |
Stylesheets to load with the preview, relative to the definition. |
assets |
Extra local files or folders the source or a loader reads at runtime, relative to the definition. |
environment |
A module, relative to the definition, that wraps or configures every scenario. See Environments. |
setup, play, ready |
Lifecycle hooks for every scenario. |
inputs, fixtures, and globals must be plain, cloneable data.
Scenarios
Each scenario can set:
label, the name in the sidebar. It defaults to the ID in sentence case, sois-busyreads Is busy.inputs,fixtures, andglobals, which override the preview’s values key by key; see What you can set, and where.source, to render a different entry or export in this scenario.requests, tried before the preview’s request mocks.setup,play, andreadyhooks.
The first scenario is the one a preview opens in. Every scenario also opens directly
with ?scenario=<id> on the preview’s address; an unknown scenario shows an error.
A preview without scenarios has one scenario, default.
SVG icon sprites registered when your preview module loads remain available when you switch scenarios or return to that preview.
Returning to a preview preserves form edits, filters, scroll, open menus, and live application state. The canvas keeps up to three previews you left loaded for 15 minutes. Reload starts the current preview again; Reset scenario restores its declared inputs. A source change rebuilds the preview. Closing the canvas releases the previews it kept.
The <html> element carries data-wb-scenario with the current scenario ID, so CSS
keyed off it works as it does in design pages.
Multiple artboards
Use artboards when one page contains several independently sized examples.
Scenarios remain alternatives selected with the scenario switcher; declaring scenarios
does not create artboards. A page may have both: the selected scenario applies to
each of its declared artboards.
artboards: {
info: { label: 'Info', width: 560, height: 79 },
success: {
label: 'Success', width: 560, height: 119,
inputs: { tone: 'success', title: 'Import complete' },
},
}
Declare 1–32 artboards with kebab-case IDs. These are children of one page,
not scenario entries or additional pages in the sidebar. Each renderer receives
context.artboard and its own inputs. Inputs merge from the preview, then the
artboard, then the selected scenario, then temporary control edits. Reset restores
that artboard’s authored inputs. The page’s supported sizes must permit its
dimensions; include Resizable for arbitrary dimensions.
Artboard labels remain selectable while their previews initialize. You can pan and zoom during loading. With the canvas focused, Left and Right select and center neighboring artboards. Only the selected artboard runs its preview. The others show a background image of it, or, when they are large enough on screen to read, a static copy of the page without scripts; see Using the canvas. If an artboard’s background image cannot be rendered, its label shows the reason; it is tried again after the next source edit, or when the artboard comes back into view.
Select an artboard to interact with it. Once you click or type in it, its application state is kept when you select another one, so returning to it keeps its document, inputs and scroll position. Selecting artboards only to look at them keeps nothing. Up to eight artboards keep application state; using a ninth releases the one used longest ago, and a message names it. A released artboard shows a kept image of what you did. Release, in the selected artboard’s label, does the same on request: it keeps that image and ends its document. Restart, in the same place once released, starts a fresh document: application drafts, counters and other JavaScript state reset, while Workbench annotations and input overrides survive.
Capture includes the complete declared group. It uses each artboard’s running document or its kept image, and starts artboards that never ran one at a time. The background images are not used. If a kept image is out of date after a source edit, capture fails and asks you to restart that artboard rather than leaving it out.
For a component that should fit its content, put data-wb-fit-content on its
origin-aligned root and remove surrounding padding, backgrounds and viewport
minimum heights. Natural bounds follow content edits independently per artboard.
Adapters
adapter picks how the source renders. The built-in adapters are html,
react, vue, astro, and react-native-web; see the table at the top of
this page for each one’s guide. Any other name must be
registered.
Data, controls, and actions
A preview gets the data its real page would load, and you can change it per scenario and while you review. Preview data, mocks, and actions covers all of it:
- Inputs and controls: props for the component, and fields under Preview controls that edit them live. Reset scenario drops your edits and the action log.
- Fixtures and globals: data and settings for the code around the component.
- Environments: providers, plugins, stores, and setup, for one preview or,
from
workbench.config.ts, for the whole project. - Request mocks: answers to the page’s own
fetchand XMLHttpRequest calls, for empty, loading, error, and offline scenarios. - Actions: what the page tried to do, listed under Actions in Preview controls.
- Links and navigation: links that open other previews, with the top bar’s Actions switch on.
Lifecycle hooks
Hooks and sources receive a context with id, scenario, inputs, fixtures,
globals, an abort signal, action(name, ...values), navigate(to), and
error(error). Examples in a page’s docs get the same
context, with empty inputs, fixtures, and globals.
setup(context)runs before the source mounts and may return a cleanup function. It runs from the project’s environment, then the preview’senvironment, then the preview, then the scenario. Request mocks are already active, sosetupcan fetch.play({ canvas, ...context })runs after mounting, for an interaction sequence such as opening a menu. The preview’s runs before the scenario’s.ready(context)runs last, for anything the preview must wait for.
An environment module can export setup and
ready too, and a hook for its adapter, such as wrap for React.
A preview is ready once its hooks finish, its fonts load, and its visible
images load or 3 seconds pass. Screenshots and handoffs wait for that, and fail
with the rendering error, or with Workbench preview did not finish rendering before capture after 8 seconds.
Before a preview renders again, its signal is aborted and cleanups run in
reverse order. Tie subscriptions, timers, and listeners to context.signal or a
cleanup. A failed cleanup doesn’t stop the others, and Reset scenario recovers
after a failed render.
Errors are shown in the preview’s frame: thrown errors, rejected promises,
React error boundaries, Vue’s error handler, and anything a custom adapter
passes to context.error(error).
An error after the first render also makes the artboard unavailable for capture until it recovers. A declared artboard that fails shows its error and starts again after the next save or resize, or with Release and then Restart. An ordinary preview can use Reset scenario to render again.
Saving a file updates the open previews that use it, usually within a fraction of a second, without reloading the canvas:
- React components keep their state through React Fast Refresh, as long as the order of their hooks is unchanged.
- Vue components update through Vue’s hot reload. A template or style edit keeps the component’s state; a script edit resets it.
- Stylesheets, CSS modules, and Vue style blocks are replaced in place.
- HTML and Astro previews render again in place, with the selected scenario and inputs.
- Saving the definition, an environment, or a module that can’t update in place reloads the preview, keeping its scenario, size, and inputs.
- Saving
workbench.config.tsrestarts the compilers and reloads the open previews. - A syntax error shows in the frame, and the next good save recovers it.
If you add or remove a definition, or change its title or scenarios, run
Workbench: Refresh Pages to update the sidebar.
Workbench compiles previews with Rspack, bundled with the extension. It starts building when the project opens, and builds all of the project’s previews and docs examples together, so code they share loads once: moving to another page loads only that page’s own code. The saved page list and build cache are kept in the system’s temporary folder, never in your project, and are reused when Workbench restarts. Your project does not need to install a compiler.
Register other technologies
Adapter names aren’t a fixed list. workbench.config.ts at the project root,
or the file named by previews.config, registers
adapters and sets Rspack rules, plugins made with Workbench’s helpers, aliases, dedupe,
resolveExtensions, and define for every preview. An adapter whose name isn’t built in or
registered fails with Unknown adapter. See Custom adapters.
Compare a design with a preview
A page can show a preview as a lens next to its design, with a workbench
implementation. See
Compare a design with a Workbench preview.
Types
Install the authoring types so tsc and your editor resolve
@canonic2/workbench:
npm install --save-dev @canonic2/workbench
Use pnpm add -D or yarn add -D with those package managers. The types
check that each scenario’s inputs match the preview’s. Workbench still compiles
previews with its own copy, so the installed version affects types only; keep
it at the version of your extension to type the newest fields.
Without an installed package, the init command below writes the same types to
a workbench-env.d.ts file. Include that file in your tsconfig.json.
Command-line tools
The extension includes the workbench-server command in its install folder,
at server/bin/<platform>-<arch>/workbench-server. Project code in
definitions and configuration runs on Node 24 or later: the node on your
PATH, or the program --node names.
~/.vscode/extensions/canonic.canonic-workbench-<version>/server/bin/darwin-arm64/workbench-server check .
| Command | What it does |
|---|---|
init <project> |
Writes workbench-env.d.ts, the types for @canonic2/workbench, and a workbench.yaml named after the folder. Existing files are left alone. |
list <project> |
Prints, as JSON, the previews, docs pages and definition errors Workbench finds. |
check <project> |
Finds and compiles every preview without opening a browser. Prints Built <id> for each, lists every failure, and exits with an error if there were any. |
build <project> [output] |
Writes the standalone viewer to output, or workbench-static in the project. The folder must be empty or missing. Successful previews are written even when others fail; failures are listed and the exit code is nonzero. |
Portable exports
Export… › Source package (ZIP) includes compiled previews in a browser/
folder, alongside their editable sources. See
Design-system export. Serve the extracted folder
with any static HTTP server and open browser/index.html. The build command
writes the same viewer on its own. Viewing it needs no Workbench, Electron,
package installation, or build step.
The viewer has:
- a searchable list of previews, and the build warnings, if any,
- Scenario and Size menus, with Width and Height for Resizable,
- Reload, and Preview controls with the same inputs, reset, actions, and documentation as the canvas,
- Open preview, which opens the preview on its own page. That page also
accepts
?scenario=<id>.
The viewer’s address keeps the preview, scenario, size, and resizable dimensions, so you can copy it to share a selection.
Astro previews carry every authored scenario but no input controls; see Astro portable exports.