canvas-workbench

Project type

Before applying this skill, check package.json for a dependency named @drupal-canvas/headless or starting with @drupal-canvas/headless-. If one is present, this is a Canvas Headless codebase — read canvas-headless first. Workbench currently supports React projects only: use it in React headless projects (Next.js, TanStack Start), but in Nuxt and Astro projects verify components through the framework dev server instead. If no such dependency is present, this is a Canvas-rendered React codebase: components are React (index.jsx/.tsx) and everything in this skill applies as written. These are the only two project types.

Installation gate

Before trying to use Workbench, detect the project's package manager and use its executable runner for @drupal-canvas/workbench.

Preferred commands:

• npm: npx @drupal-canvas/workbench
• pnpm: pnpm dlx @drupal-canvas/workbench
• bun: bunx @drupal-canvas/workbench
• yarn: yarn dlx @drupal-canvas/workbench

Choose the command that matches the repository's package manager. Use lockfiles and existing project conventions to decide.

If the package runner or @drupal-canvas/workbench is not available, stop and tell the user that Canvas Workbench is not available in the current environment. Ask whether they want you to install it. If they say yes, install @drupal-canvas/workbench as a dev dependency with the matching package manager:

• npm: npm install --save-dev @drupal-canvas/workbench
• pnpm: pnpm add --save-dev @drupal-canvas/workbench
• bun: bun add --dev @drupal-canvas/workbench
• yarn: yarn add --dev @drupal-canvas/workbench

After installation completes, use the matching runner command and continue with Workbench verification. If the user says no, stop and do not guess alternate startup commands.

Configuration gate

Workbench does not require a canvas.config.json file when the project uses the default Canvas layout.

Before starting Workbench, check whether the project appears to use the default paths:

• componentDir: project root
• pagesDir: ./pages
• aliasBaseDir: src
• globalCssPath: ./src/components/global.css

If the project uses those defaults and canvas.config.json is missing, proceed without creating one.

If the project uses different component paths, pages paths, @/ import resolution, or global CSS entrypoints, add or update canvas.config.json in the project root before starting Workbench. Set only the options the project needs.

Example:

{
  "componentDir": "./src/components",
  "pagesDir": "./pages",
  "aliasBaseDir": "src",
  "globalCssPath": "./src/global.css"
}

Start Workbench

When Workbench verification is needed and the package-runner command is available:

1. Run the matching Workbench command from the project root.
2. Treat it as a long-running local dev server process.
3. Read the startup output and use the local URL it prints.
4. Leave the server running while you verify the result.

If a Workbench server is already running for the current project, reuse it instead of starting a second instance.

Page, site, and client context

Both interactive previews and preview-build output supply the providers for usePageContext(), useSiteContext(), and useJsonApiClient() automatically. Do not add component-level providers or inject Drupal globals to make these hooks work. Site data and client configuration come from the Vite integration's public /canvas/api/v0/site-data request, with existing configuration fallbacks.

Workbench does not load the current Drupal page's context. Its intentional page defaults are:

{ pageTitle: '', breadcrumbs: [], mainEntity: null }

An empty breadcrumb trail or hidden entity-dependent component may therefore be correct. Verify real page context in Drupal or the routed headless application; do not invent JSON:API payloads or page-context fixtures in component mocks to conceal these defaults. Keep using real loading, empty, and error states.

Edits to an existing mock refresh the mounted preview in place and preserve component state. Adding/removing discovery files can remount the iframe. When checking initial state, explicitly reload rather than assuming a mock edit reset it.

Verification workflow

Workbench is the runtime surface for local preview verification. When verification is iterative, reuse the same Workbench server and preview route across fix/review loops.

Use Workbench as part of the normal implementation loop:

1. Start or reuse Workbench.
2. Open the relevant component preview state or page preview.
3. Verify that the requested change renders correctly.
4. If the result is wrong, update the implementation and verify again.
5. Finish only after Workbench verification passes, or explain clearly what blocked verification.

Scope

This skill is for starting and using Workbench and for coordinating page/mock authoring. It is not the source of truth for the Canvas component contract.

• Use canvas-component-definition when creating or validating the component structure, component.yml, naming, or mock coverage expectations.
• Use canvas-page-definition when creating or validating page JSON files, page structure, or page schema requirements.
• Use canvas-component-definition/references/component-mocks.md when you need to author or validate mocks.json.
• Use references/components.md when you need the Workbench-specific component review flow and where component preview files live.
• Use references/pages.md when you need the Workbench-specific page preview flow and configured page location.