mcpField
C
canvas-workbench

canvas-workbench

github.com/drupal-canvas测试与质量3183 次安装5 周前更新
代码仓库

关于 canvas-workbench

canvas-workbench 是用于 React Canvas 项目的本地预览与验证技能，面向开发和检查组件、页面的工作流。它指导 Workbench 的安装、配置与复用，并强调通过实际预览反复核验改动。

主要功能

  1. 01识别 Canvas 项目类型
  2. 02按包管理器启动 Workbench
  3. 03按需配置 canvas.config.json
  4. 04复用本地预览服务器
  5. 05验证组件与页面渲染
  6. 06协调页面和模拟数据编写

适用场景

  1. 01检查 React 组件改动的渲染结果
  2. 02预览页面并迭代修正实现
  3. 03按项目路径配置 Canvas Workbench
  4. 04复用预览服务器完成多轮核验

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/drupal-canvas/skills --skill canvas-workbench

安装后在 Claude Code 中输入/canvas-workbench确认已加载。

附带文件references/components.mdreferences/pages.md

详细介绍

项目类型

应用此技能前，请检查 package.json 中是否有名为 @drupal-canvas/headless 或以 @drupal-canvas/headless- 开头的依赖。如果存在，则这是一个 Canvas Headless 代码库——请先阅读 canvas-headless。Workbench 目前仅支持 React 项目：可在 React headless 项目（Next.js、 TanStack Start）中使用，但在 Nuxt 和 Astro 项目中，请改用框架开发服务器验证组件。如果不存在此类依赖，则这是一个 Canvas 渲染的 React 代码库：组件使用 React（index.jsx/.tsx），本技能中的所有内容均按原样适用。项目类型仅有这两种。

安装检查

尝试使用 Workbench 前，请检测项目的包管理器，并使用其可执行运行器运行 @drupal-canvas/workbench。

首选命令：

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

选择与代码库包管理器匹配的命令。请根据锁文件和项目现有约定进行判断。

如果包运行器或 @drupal-canvas/workbench 不可用，请停止，并告知用户当前环境中无法使用 Canvas Workbench。询问用户是否希望安装。如果用户同意，请使用匹配的包管理器将 @drupal-canvas/workbench 安装为开发依赖：

  • 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

安装完成后，使用匹配的运行器命令，并继续进行 Workbench 验证。如果用户拒绝，请停止，不要猜测其他启动命令。

配置检查

如果项目使用 Canvas 默认布局，Workbench 不需要 canvas.config.json 文件。

启动 Workbench 前，请检查项目是否采用以下默认路径：

  • componentDir：项目根目录
  • pagesDir：./pages
  • aliasBaseDir：src
  • globalCssPath：./src/components/global.css

如果项目使用这些默认值，且缺少 canvas.config.json，则无需创建该文件，直接继续。

如果项目使用不同的组件路径、页面路径、@/ 导入解析方式或全局 CSS 入口，请在启动 Workbench 前，在项目根目录中添加或更新 canvas.config.json。只设置项目需要的选项。

示例：

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

启动 Workbench

需要使用 Workbench 进行验证且包运行器命令可用时：

  1. 在项目根目录运行匹配的 Workbench 命令。
  2. 将其视为长时间运行的本地开发服务器进程。
  3. 阅读启动输出，并使用其中显示的本地 URL。
  4. 验证结果期间保持服务器运行。

如果当前项目已有运行中的 Workbench 服务，请复用它，不要启动第二个实例。

页面、站点和客户端上下文

交互式预览和 preview-build 输出都会自动提供 usePageContext()、useSiteContext() 和 useJsonApiClient() 的 providers。不要添加组件级 providers，也不要注入 Drupal 全局变量来让这些 hooks 正常工作。站点数据和客户端配置来自 Vite 集成发出的公开 /canvas/api/v0/site-data 请求，并使用现有配置作为回退。

Workbench 不会加载当前 Drupal 页面的上下文。其有意设置的页面默认值为：

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

因此，面包屑轨迹为空或依赖实体的组件被隐藏，可能是正确行为。请在 Drupal 或路由化的无头应用中验证实际页面上下文；不要在组件 mocks 中编造 JSON:API 负载或页面上下文 fixture 来掩盖这些默认值。继续使用真实的加载、空和错误状态。

修改现有 mock 会就地刷新已挂载的预览，并保留组件状态。添加或移除发现文件可能会导致 iframe 重新挂载。检查初始状态时，请明确重新加载，不要假定修改 mock 会重置状态。

验证工作流

Workbench 是本地预览验证的运行时界面。在迭代验证时，请在多轮修复和审查过程中重复使用同一个 Workbench 服务和预览路由。

将 Workbench 纳入常规实现流程：

  1. 启动或复用 Workbench。
  2. 打开相关的组件预览状态或页面预览。
  3. 验证请求的更改是否正确呈现。
  4. 如果结果不正确，请更新实现并再次验证。
  5. 只有在 Workbench 验证通过后才完成；如果验证受阻，请清楚说明原因。

范围

此 skill 用于启动和使用 Workbench，以及协调页面和 mock 编写工作。它不是 Canvas 组件规范的权威来源。

  • 创建或验证组件结构、component.yml、命名或 mock 覆盖预期时，请使用 canvas-component-definition。
  • 创建或验证页面 JSON 文件、页面结构或页面 schema 要求时，请使用 canvas-page-definition。
  • 需要编写或验证 mocks.json 时，请使用 canvas-component-definition/references/component-mocks.md。
  • 需要了解 Workbench 专属的组件审查流程以及组件预览文件所在位置时，请使用 references/components.md。
  • 需要了解 Workbench 专属的页面预览流程以及配置的页面位置时，请使用 references/pages.md。

评论

支持 Markdown