SuperAPI AI 工具集

convex-create-component

编程与开发

查看项目

更新于 10-16 16:06

技能介绍

Convex Create Component 是 Convex 官方 agent-skills 仓库中的一项技能,用于在现有 Convex 应用中创建可复用的 Convex 组件:这些组件拥有隔离的数据表和面向应用的小型 API。

用途

该技能适用于以下场景:在现有应用中创建新的 Convex 组件;将可复用的后端逻辑抽取为组件;构建应拥有自己数据表与工作流的第三方集成;为跨多个应用复用而打包 Convex 功能。它明确指出不适用的情况:属于主应用的一次性业务逻辑;不需要 Convex 数据表或函数的轻量工具;应保留在 convex/ 中的应用级编排;普通 TypeScript 库就足够的场景。

工作流程

技能要求先询问用户正在构建什么以及最终目标;如果仓库已能明显看出答案,则说明并确认后再继续。随后通过决策树选择形态并阅读匹配的参考文件(references/local-components.md、references/packaged-components.md 或 references/hybrid-components.md),且只读取一个参考文件。接着判断组件是否合理——如果功能不需要隔离的数据表、后端函数或可复用的持久化状态,就优先使用普通应用代码或常规库。之后为以下内容制定简短计划:组件拥有哪些数据表、暴露哪些公开函数、必须从应用传入哪些数据(认证、环境变量、父级 ID)、哪些保留在应用中作为包装器或 HTTP 挂载。随后创建组件结构(convex.config.ts、schema.ts 和函数文件),使用组件自身的 ./_generated/server 导入实现函数(而非应用的生成文件),通过 app.use(...) 将组件接入应用(若应用尚无 convex/convex.config.ts 则创建它),并从应用通过 components.<name> 使用 ctx.runQuery、ctx.runMutation 或 ctx.runAction 调用组件。如果 React 客户端、HTTP 调用方或公开 API 需要访问,应在应用中创建包装函数,而不是直接暴露组件函数。最后运行 npx convex dev,在完成前修复代码生成、类型或边界问题。

组件形态选择

技能让用户确认目标后选择一条路径:仅用于此应用的组件选 Local(references/local-components.md);需要发布或跨应用共享选 Packaged(references/packaged-components.md);用户明确需要本地加共享库代码选 Hybrid(references/hybrid-components.md);不确定时默认 Local。除非用户明确想要 npm 包,否则默认使用本地组件:放在 convex/components/<componentName>/ 下,用自己的 convex.config.ts 中的 defineComponent(...) 定义,通过应用 convex/convex.config.ts 的 app.use(...) 安装,并让 npx convex dev 生成组件自己的 _generated/ 文件。资料中提供了最小本地组件骨架示例,包含 components/notifications 的 convex.config.ts、schema.ts、lib.ts,以及应用侧的 convex.config.ts 和 notifications.ts 包装器。函数调用路径形如 components.notifications.lib.send。

关键规则

认证留在应用中,因为组件内不可用 ctx.auth。环境访问留在应用中,因为组件函数无法读取 process.env。父应用 ID 以字符串跨边界传递,因为 Id 类型在面向应用的 ComponentApi 中变为普通字符串。不要在组件参数或 schema 中对应用拥有的表使用 v.id("parentTable"),因为组件无法访问应用的 table 命名空间。从组件自身的 ./_generated/server 导入 query、mutation 和 action,而非应用的生成文件。不要直接向客户端暴露组件函数;需要客户端访问时创建应用包装器,因为组件是内部的,需要应用提供的认证/环境接线。若组件定义 HTTP 处理器,需在应用的 convex/http.ts 挂载路由,因为组件不能注册自己的 HTTP 路由。若组件需要分页,使用 convex-helpers 的 paginator 而非内置 .paginate(),因为 .paginate() 无法跨组件边界工作。为被查询字段定义索引,而不是在数据库查询后使用 Convex .filter()。为所有公开组件函数添加 args 和 returns 校验器,因为组件边界需要显式类型契约。

高级模式与验证

资料还提到更多模式(函数句柄用于回调、从 schema 派生校验器、使用 globals 表的静态配置、基于类的客户端包装器)见 references/advanced-patterns.md。验证按顺序尝试:npx convex codegen --component-dir convex/components/<name>、npx convex codegen、npx convex dev。新仓库在配置 CONVEX_DEPLOYMENT 之前这些命令可能失败;在 codegen 运行之前,组件本地 ./_generated/* 导入和应用侧 components.<name>... 引用都无法通过类型检查;若验证因 Convex 登录或部署设置受阻,应停下来询问用户该步骤而不是猜测。

限制

资料的说明以工作流、规则与示例代码为主,未提供收费、价格、平台兼容性或性能效果等信息,这些内容暂未提供。