用途:本技能用于指导编写 Convex 组件——隔离、可复用的后端模块,每个组件拥有自己的 schema、函数与命名空间,便于模块化架构和通过 NPM 分发库。适用于构建可复用后端模块、打包 Convex 功能供 NPM 发布、创建独立子系统的 schema、集成第三方 Convex 组件,以及构建带 Convex 后端的库(如限流器、工作池)。
主要能力:组件分为本地(convex/myComponent/)、打包(node_modules/@org/component/)与混合(packages/my-component/)三类。组件目录包含 convex.config.ts(defineComponent 定义)、schema.ts(defineSchema/defineTable)、public.ts(公开 API)、internal.ts(内部函数)与 _generated/。宿主应用在 convex/convex.config.ts 中用 defineApp 与 app.use(myComponent, { name: "cache" }) 挂载,并通过 components.<name>.<module>.<function> 调用,如 ctx.runMutation(components.cache.public.set, {...})。可提供基于类的客户端封装简化调用。
使用方式:编写组件后,在组件目录执行 npx convex codegen 生成类型,再 npm run build 构建并 npm publish 发布。测试使用 convex-test 配合 vitest,可调用 t.mutation/t.query 并直接插入种子数据。
限制:组件 ID 为不透明字符串,不能使用 Id<"table">;组件无法访问 process.env,配置需通过函数参数显式传入;组件没有 ctx.auth,用户信息需由宿主应用传入;分页游标为字符串。代码库启用 @typescript-eslint/no-explicit-any,禁止使用 any,否则构建失败。