Convex Create Component 是一个围绕 Convex 组件开发的技能模板,目标是帮助开发者创建边界清晰、面向应用暴露小型 API 的可复用 Convex 组件。
适用场景:在现有应用中创建新 Convex 组件;将可复用后端逻辑抽取为组件;构建应拥有自己数据表与工作流的第三方集成;打包可在多个应用间复用的 Convex 功能。
不适用场景:属于主应用的一次性业务逻辑;不需要 Convex 表或函数的轻量工具;应保留在 convex/ 目录的应用级编排;普通 TypeScript 库即可满足的情况。
使用方式:先确认用户要构建什么及最终目标,再依据决策树选择组件形态——仅用于当前应用的本地组件、发布或跨应用共享的打包组件、本地加共享库代码的混合形态,或默认选择本地组件。随后阅读对应的一个参考文件,判断组件是否确有必要,并规划组件拥有的表、公开函数、需从应用传入的数据(认证、环境变量、父级 ID)以及保留在应用侧作为包装器或 HTTP 挂载的部分。接着用 convex.config.ts、schema.ts 和函数文件创建组件结构,函数从组件自身的 ./_generated/server 导入,并通过应用 convex/convex.config.ts 中的 app.use(...) 接入,再用 ctx.runQuery、ctx.runMutation 或 ctx.runAction 调用。若 React 客户端、HTTP 调用方或公共 API 需要访问,应在应用中创建包装函数而非直接暴露组件函数。最后运行 npx convex dev 修复代码生成、类型或边界问题。
关键规则:认证保留在应用侧,因为组件内无法使用 ctx.auth;环境变量访问同样保留在应用侧,组件函数无法读取 process.env;父应用 ID 以字符串跨边界传递,因为 Id 类型在面向应用的 ComponentApi 中变为普通字符串;组件参数或 schema 中不要对应用自有表使用 v.id("parentTable");从组件自身生成的 server 文件导入 query、mutation 和 action;不直接向客户端暴露组件函数;组件定义 HTTP 处理器时,将路由挂载在应用的 convex/http.ts;组件需要分页时使用 convex-helpers 中的 paginator;为查询字段定义索引而非使用 .filter();所有公开组件函数添加 args 与 returns 校验器。
验证顺序为 npx convex codegen --component-dir convex/components/<name>、npx convex codegen、npx convex dev。新仓库在配置 CONVEX_DEPLOYMENT 前可能失败;代码生成运行前,组件本地 _generated 导入和应用侧 components.<name> 引用无法通过类型检查;若验证因 Convex 登录或部署设置受阻,应停止并请用户完成该步骤。官方文档为 Authoring Components。