Custom adapters and compiler settings
Workbench previews ship with adapters for HTML, React, Vue, Astro, and React
Native Web. To preview anything else, such as web components, Svelte, Solid, or
an in-house rendering library, register an adapter in workbench.config.ts. The
same file holds the compiler settings every preview shares: compiler plugins and
loader rules, import aliases, deduplicated packages, file extensions, and
build-time constants.
Use this guide when:
- your components aren’t rendered by a built-in adapter,
- a file type needs a compiler step Workbench doesn’t have, such as
.sveltefiles or?inlineimports, - imports need redirecting to mocks or to one copy of a package,
- you want to replace how a built-in adapter mounts components.
For the definition keys, controls, hooks, and the command-line checker, see TypeScript Workbench previews.
Requirements
- A
workbench.yamlat the project root, and a trusted workspace. Plugins, loaders and runtimes run project code. - Whatever your adapter renders with, installed in your project. Workbench bundles your runtime module with the project’s own packages and installs nothing.
- Plugins and loaders for Rspack, which compiles previews. Most webpack loaders work as Rspack rules. Vite, Rollup, and Babel plugins need an equivalent loader or plugin.
Example: web components
This example previews a custom element whose shadow DOM styles are imported with
a Vite-style ?inline suffix. It registers a web-components adapter, with a
rule that loads ?inline imports as text. It needs no packages.
acme-ui/
├── workbench.yaml
├── workbench.config.ts
├── preview/
│ └── web-components.ts
└── src/
├── acme-button.css
├── acme-button.ts
├── acme-button.workbench.ts
├── acme-theme.ts
└── inline.d.ts
workbench.config.ts registers the adapter and its rule:
import { defineConfig } from '@canonic2/workbench';
export default defineConfig({
adapters: {
'web-components': {
runtime: './preview/web-components.ts',
// Imports ending in `?inline` load the file's text, for shadow DOM styles.
rules: [{ resourceQuery: /inline/, type: 'asset/source' }],
},
},
});
preview/web-components.ts is the runtime. It creates the element, sets the
inputs as properties, and logs the element’s events in Actions:
import type { PreviewContext } from '@canonic2/workbench';
type ElementClass = CustomElementConstructor & { events?: string[] };
export async function mount(
canvas: HTMLElement,
source: ElementClass,
context: PreviewContext,
environment: { wrap?: (element: HTMLElement, context: PreviewContext) => HTMLElement },
) {
const tag = customElements.getName(source);
if (!tag) throw new Error('Define the element with customElements.define before exporting it.');
const element = document.createElement(tag);
Object.assign(element, context.inputs);
for (const name of source.events ?? []) {
element.addEventListener(name, event => context.action(name, (event as CustomEvent).detail), {
signal: context.signal,
});
}
canvas.append(environment.wrap ? environment.wrap(element, context) : element);
// Lit and similar libraries render asynchronously.
await (element as { updateComplete?: Promise<unknown> }).updateComplete;
return () => canvas.replaceChildren();
}
src/acme-button.ts is the component:
import styles from './acme-button.css?inline';
export class AcmeButton extends HTMLElement {
static events = ['acme-press'];
label = 'Continue';
disabled = false;
connectedCallback() {
const root = this.shadowRoot ?? this.attachShadow({ mode: 'open' });
const sheet = new CSSStyleSheet();
sheet.replaceSync(styles);
root.adoptedStyleSheets = [sheet];
const button = document.createElement('button');
button.textContent = this.label;
button.disabled = this.disabled;
button.addEventListener('click', () => {
this.dispatchEvent(new CustomEvent('acme-press', { detail: this.label }));
});
root.replaceChildren(button);
}
}
customElements.define('acme-button', AcmeButton);
src/acme-button.css:
button {
background: #4f46e5;
border: 0;
border-radius: 8px;
color: white;
font: 600 14px/1 system-ui, sans-serif;
padding: 12px 16px;
}
button:disabled {
opacity: 0.5;
}
src/inline.d.ts types the ?inline imports for your editor:
declare module '*?inline' {
const text: string;
export default text;
}
src/acme-theme.ts is the preview’s environment. The runtime above calls its
wrap:
import type { PreviewContext } from '@canonic2/workbench';
export function wrap(element: HTMLElement, context: PreviewContext) {
const theme = document.createElement('div');
theme.dataset.theme = String(context.globals.theme ?? 'light');
theme.append(element);
return theme;
}
src/acme-button.workbench.ts uses the adapter by name:
import { definePreview } from '@canonic2/workbench';
export default definePreview({
id: 'components/acme-button',
title: 'Components/Button',
adapter: 'web-components',
source: { entry: './acme-button.ts', export: 'AcmeButton' },
environment: './acme-theme.ts',
globals: { theme: 'light' },
inputs: { label: 'Continue', disabled: false },
controls: {
label: { type: 'text' },
disabled: { type: 'boolean' },
},
scenarios: {
default: {},
disabled: { inputs: { disabled: true } },
},
});
Run Workbench: Refresh Pages. Button appears under Components
with Default and Disabled scenarios. Editing label in
Preview controls mounts the element again with the new value, and pressing
the button logs acme-press in Actions. The
checker reports:
$ <extension>/server/bin/<platform>-<arch>/workbench-server check acme-ui
Built components/acme-button
The runtime module
runtime is a browser module, relative to the project root, that exports
mount(canvas, source, context, environment). Workbench bundles it with each
preview that uses the adapter, so it can import your framework like any other
module.
| Argument | Value |
|---|---|
canvas |
The empty element to render into. |
source |
The export of the scenario’s source.entry named by source.export (default when omitted), after your rules and plugins compile it. |
context |
The preview context: id, scenario, inputs, fixtures, globals, signal, action, navigate, and error. |
environment |
Everything the definition’s environment module exports, or {} when it has none. Define your own hooks here, such as wrap above. With a project-wide environment too, the two are combined: setup, mount, ready, configure, and wrap run both, the project’s outside, and other exports come from the definition’s module first. |
mountmay return a cleanup function, or a promise for one. Workbench waits for the promise before it runsplayandreadyhooks and marks the preview ready, so resolve it once the component has rendered.- Workbench calls
mountagain for every scenario change, input edit, and Reset scenario, after abortingcontext.signaland running the previous cleanup. Remove anything you added outsidecanvasin the cleanup. - An error thrown by
mount, or a rejected promise, shows in the frame. Pass errors that happen later, such as in an event handler, tocontext.error(error). - How inputs reach the component is up to the runtime: props, properties, attributes, or a store.
- The runtime needs nothing for request mocks or links: Workbench answers the page’s requests and handles its links whatever renders it.
Previews with custom adapters export to the portable viewer like any other, with their controls.
Docs page examples
A registered adapter also renders the examples in a page’s
docs. Name it as the adapter of a docs lens:
implementations:
web:
kind: docs
label: Web components
adapter: web-components
Workbench bundles the lens’s example source with the runtime and the adapter’s
rules and plugins, and calls mount(canvas, source, context, environment) once per
example:
canvasis the example’s panel, andsourceis the example: a file’s default export, for a folder source, or one named export, for a file source.context.idis the example’s ID.inputs,fixtures, andglobalsare empty, since examples have no inputs or controls.environmentcombines the project’s environment for the adapter and the lens’senvironment, as for a preview. Itssetupruns once before the examples mount, andreadyonce after.- In a folder source, only files ending in
.ts,.tsx,.js,.jsx, or.mjsare examples. For components in other file types, such as.svelte, write one script file per example that exports the component, or export them by name from one file.
A built-in adapter replaced in adapters is replaced for docs examples too.
Configuration file
Workbench reads workbench.config.ts at the project root. To use another file
inside the project, set previews.config in
workbench.yaml. Saving the file, or a file it imports, restarts the preview
compilers and reloads the open previews.
Workbench runs the file in Node. Relative imports are bundled with it; packages
are loaded from your project’s node_modules. defineConfig from
@canonic2/workbench only adds types.
import { defineConfig } from '@canonic2/workbench';
export default defineConfig({
adapters: { /* name: { runtime, rules, plugins } */ },
environment: './src/workbench/environment.tsx',
rules: [],
plugins: [],
aliases: {},
dedupe: [],
resolveExtensions: [],
define: {},
});
| Key | Type | Description |
|---|---|---|
adapters |
map of name to { runtime, rules?, plugins? } |
Adapters that definitions name in adapter. |
environment |
path, or map of adapter name to path | An environment around every preview, or around each adapter’s previews, relative to the project root. |
rules |
list of Rspack module rules | Loader rules for every preview. |
plugins |
list of compiler plugins | Plugins for every preview. |
aliases |
map of import specifier to path or package | Redirects exact imports. |
dedupe |
list of package names | Packages resolved from the definition’s folder. |
resolveExtensions |
list of extensions | The extensions tried for imports without one. Replaces the default list. |
define |
map of expression to code string | Constants replaced at build time. |
adapters
Each key is the name a definition gives as adapter. Definitions only accept
kebab-case names, such as web-components. Each value has:
runtime: the runtime module, relative to the project root.rulesandplugins: rules and plugins for previews that use this adapter only.defineAdapterfrom@canonic2/workbenchtypes one adapter on its own.
rules and plugins
Workbench compiles previews with Rspack’s compiler.
rules are module rules: they
pick a loader or a module type for matching files. plugins are the compiler
capabilities below, made with helpers from @canonic2/workbench. Global ones
apply to every preview, and an adapter’s to the previews that use it.
Workbench’s own rules and plugins come first.
| Helper | What it does |
|---|---|
virtualModule({ id, source }) |
Serves a module made from source when code imports id, such as virtual:build-info |
resolveImport({ request, to, importer? }) |
Sends an exact import to another file: from every file, or only from files importer matches |
importGlob({ include? }) |
Expands import.meta.glob(...) at build time, as Vite does |
svgSprite({ dirs, symbolId?, register?, names? }) |
Builds an SVG sprite from a folder of icons, as vite-plugin-svg-icons does |
import { defineConfig, virtualModule, resolveImport, importGlob, svgSprite } from '@canonic2/workbench';
export default defineConfig({
plugins: [
virtualModule({ id: 'virtual:build-info', source: "export const buildInfo = 'Acme build 42';" }),
// The first match wins: native screens get the native entry, other files the web one.
resolveImport({ request: '@acme/ui', importer: 'apps/mobile/**', to: './packages/ui/src/native.ts' }),
resolveImport({ request: '@acme/ui', to: './packages/ui/src/index.ts' }),
importGlob(),
svgSprite({ dirs: ['packages/ui/src/icons'], symbolId: 'icon-[name]' }),
],
});
resolveImport:requestmatches one whole import.tois a file relative to the project root, or a package.importeris a glob, or a list of globs, over the importing file’s path from the project root, or a regular expression over its absolute path.importGlob: each call’s patterns must be string literals starting with./,../or/(the project root). Keys are written as the pattern is, in name order.eager,import,queryandexhaustivework as in Vite; a!pattern leaves files out.includelimits the transform to some files, as a rule’sincludedoes: a path from the project root, a regular expression, or a list of them. Calls in comments and strings are left as written.svgSprite: every.svgindirs, relative to the project root, becomes a<symbol>.symbolIdnames each one:[dir]is the icon’s folder insidedirs(with-for/) and[name]its file name, and the default isicon-[dir]-[name]. Importingvirtual:svg-icons-registerinserts the sprite into the page;virtual:svg-icons-namesexports the IDs.registerandnamesrename those imports. Each symbol keeps the icon’s view box, or takes one from its width and height; IDs inside an icon are prefixed with its symbol ID, and so are the references to them.- Adding, editing or deleting a file a plugin reads, such as an icon or a file a glob matches, rebuilds the previews that use it.
A loader is a file that exports a function from source text to module text. Name it in a rule by path, relative to the project root:
rules: [{ test: /\.tsx?$/, exclude: /node_modules/, enforce: 'pre', loader: './workbench/greeting-loader.cjs' }],
Loaders run in Node, one module at a time, with the usual loader context:
this.getOptions(), this.resourcePath, this.async(), this.addDependency()
and the like. this.emitError() fails the module’s build with its message,
as a thrown error does; this.emitWarning() reports a warning and the build
continues. this.loadModule and this.importModule are not available.
Rspack’s built-in loaders, such as builtin:lightningcss-loader, run in the
compiler itself.
Rules and plugins apply when Workbench builds previews and docs examples, live
and for the design-system export. They don’t apply
when Workbench reads a definition or this file, or in
Astro frontmatter, so a .workbench.ts
file can’t import a file that only a loader can read.
An object with apply(compiler) (an Rspack plugin) or setup(build) (an
esbuild plugin) doesn’t run: it is reported as a configuration problem and
left out. Use a helper above, or a loader rule.
- Build absolute paths from
__dirname, the folder of the configuration file. Don’t rely on the current working directory.
aliases
aliases: {
'@acme/tokens': './src/tokens.ts',
'@acme/tokens/colors': './src/tokens/colors.ts',
'acme-analytics': './preview/analytics-mock.ts',
'#runtime': 'acme-runtime',
},
- A key matches one exact package-style import:
@acme/tokensdoesn’t match@acme/tokens/colors, so list each subpath you import. Keys that start with.or/never match. - A value that starts with
., or an absolute path, is a file relative to the project root. Any other value is a package, resolved from the definition’s folder. tsconfig.jsonpathsalso apply, without an alias.- Aliases also apply to Astro frontmatter.
dedupe
dedupe: ['react', 'react-dom'],
Imports of these packages resolve from the folder of the preview definition, as if the definition imported them, instead of from the file that imports them. In a monorepo where a shared package has its own copy of a framework, this gives every module in the preview the same copy.
resolveExtensions
resolveExtensions: ['.web.ts', '.ts', '.js'],
The extensions tried, in order, for an import without one. The list replaces
the default, .tsx, .ts, .jsx, .js, .mjs, .cjs, .json, .vue,
.html, so include every extension your previews import without one. The
react-native-web adapter puts .web.tsx, .web.ts, .web.jsx, and
.web.js first when you don’t set this. It doesn’t apply to Astro frontmatter.
define
define: {
'process.env.API_URL': JSON.stringify('https://api.example.com'),
__ACME_FLAG__: 'true',
},
Each key is an identifier or property chain, and each value is the code that
replaces it, so wrap strings in JSON.stringify. Workbench sets
process.env.NODE_ENV to "development" on the canvas and "production" in
check, build, and exports; your define can override it. Defines also
apply to Astro frontmatter, where they set
import.meta.env values.
Replace a built-in adapter
Registering an adapter named html, react, vue, astro, or
react-native-web replaces the built-in one for every preview in the project:
export default defineConfig({
adapters: {
react: { runtime: './preview/react-runtime.tsx' },
},
});
Your runtime receives the selected export and does all the mounting, including
any providers. A replaced astro adapter doesn’t render on the server:
.astro files then need a rule that compiles them for the browser, or the
build fails with Module parse failed. Replacing
react-native-web keeps its react-native alias and .web.* extensions.
Errors and fixes
| Error | Where | Fix |
|---|---|---|
Unknown adapter “<name>”. Register it in workbench.config.ts. |
The frame and check |
Add the name to adapters, or fix the definition’s adapter. |
adapter must be a registered kebab-case name. |
Configuration problems | Use lowercase letters, digits, and hyphens in the adapter name. |
Module not found: Can't resolve '<path>' on a runtime path |
The frame and check |
Fix runtime. It is relative to the project root. |
adapter.mount is not a function |
The frame | Export a function named mount from the runtime. |
The selected source export does not exist for <id> — <scenario> |
The frame only; check passes |
Fix source.export, or export that name from the entry. |
Module parse failed on a file type Workbench doesn’t compile |
The frame and check |
Add a rule with a loader for the file type. |
workbench.config.ts: “<name>” is an esbuild plugin. or is a JavaScript Rspack plugin. |
Configuration problems | Use a plugin from @canonic2/workbench, or a loader rule. |
Workbench previews: <message> |
Configuration problems | workbench.config.ts threw while loading. No previews load until it’s fixed; check prints the same message. |
previews.config: must be a project-relative config file. |
Configuration problems | Point previews.config at a file inside the project. Previews stay off until it’s fixed. |
For configuration problems and the log, see A TypeScript preview is missing or broken.