Convex组件创建指南：构建可复用后端模块与第三方集成

convex-create-component by get-convex/agent-skills

6,700 周安装量

15 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/get-convex/agent-skills --skill convex-create-component

开发云服务

🇨🇳中文介绍

Convex Create Component

创建具有清晰边界和精简应用层 API 的可复用 Convex 组件。

何时使用

在现有应用中创建新的 Convex 组件
将可复用的后端逻辑提取为组件
构建应拥有自身数据表和工作流程的第三方集成
打包 Convex 功能以便在多个应用间复用

何时不使用

属于主应用的一次性业务逻辑
不需要 Convex 数据表或函数的轻量工具
应保留在 convex/ 中的应用层编排逻辑
普通 TypeScript 库即可满足需求的情况

工作流程

询问用户正在构建什么以及最终目标是什么。如果仓库信息已明确答案，请说明并确认后再继续。
使用下方的决策树选择组件形态，并阅读对应的参考文件。
判断组件是否合理。如果功能不需要独立的数据表、后端函数或可复用的持久化状态，则优先使用普通的应用代码或常规库。
制定简要计划，包括：
- 组件拥有的数据表
- 组件暴露的公共函数
- 必须从应用传入的数据（认证信息、环境变量、父级 ID）
- 保留在应用中作为包装器或 HTTP 挂载点的部分
使用 convex.config.ts、schema.ts 和函数文件创建组件结构。
使用组件自身的 ./_generated/server 导入来实现函数，而不是应用的生成文件。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

705,000 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

245,300 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

196,800 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

128,699 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

使用 app.use(...) 将组件接入应用。如果应用尚未拥有 convex/convex.config.ts，请创建它。

通过 components.<name>，使用 ctx.runQuery、ctx.runMutation 或 ctx.runAction 从应用调用组件。

如果 React 客户端、HTTP 调用者或公共 API 需要访问，请在应用中创建包装函数，而不是直接暴露组件函数。

在完成前运行 npx convex dev 并修复代码生成、类型或边界问题。

询问用户，然后选择一条路径：

目标	形态	参考文件
仅用于此应用的组件	本地组件	`references/local-components.md`
跨应用发布或共享	打包组件	`references/packaged-components.md`
用户明确需要本地 + 共享库代码	混合组件	`references/hybrid-components.md`
不确定	默认使用本地组件	`references/local-components.md`

在继续之前，请精确阅读一个参考文件。

除非用户明确需要 npm 包，否则默认使用本地组件：

将其置于 convex/components/<componentName>/ 目录下
在其自身的 convex.config.ts 中使用 defineComponent(...) 定义
在应用的 convex/convex.config.ts 中使用 app.use(...) 安装
让 npx convex dev 生成组件自身的 _generated/ 文件

一个包含一个数据表和两个函数的最小本地组件，以及应用侧的接入代码。

// convex/components/notifications/convex.config.ts
import { defineComponent } from "convex/server";

export default defineComponent("notifications");

// convex/components/notifications/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  notifications: defineTable({
    userId: v.string(),
    message: v.string(),
    read: v.boolean(),
  }).index("by_user", ["userId"]),
});

// convex/components/notifications/lib.ts
import { v } from "convex/values";
import { mutation, query } from "./_generated/server.js";

export const send = mutation({
  args: { userId: v.string(), message: v.string() },
  returns: v.id("notifications"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("notifications", {
      userId: args.userId,
      message: args.message,
      read: false,
    });
  },
});

export const listUnread = query({
  args: { userId: v.string() },
  returns: v.array(
    v.object({
      _id: v.id("notifications"),
      _creationTime: v.number(),
      userId: v.string(),
      message: v.string(),
      read: v.boolean(),
    })
  ),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("notifications")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .filter((q) => q.eq(q.field("read"), false))
      .collect();
  },
});

// convex/convex.config.ts
import { defineApp } from "convex/server";
import notifications from "./components/notifications/convex.config.js";

const app = defineApp();
app.use(notifications);

export default app;

// convex/notifications.ts  (应用侧包装器)
import { v } from "convex/values";
import { mutation, query } from "./_generated/server";
import { components } from "./_generated/api";
import { getAuthUserId } from "@convex-dev/auth/server";

export const sendNotification = mutation({
  args: { message: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) throw new Error("Not authenticated");

    await ctx.runMutation(components.notifications.lib.send, {
      userId,
      message: args.message,
    });
    return null;
  },
});

export const myUnread = query({
  args: {},
  handler: async (ctx) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) throw new Error("Not authenticated");

    return await ctx.runQuery(components.notifications.lib.listUnread, {
      userId,
    });
  },
});

注意引用路径的形态：convex/components/notifications/lib.ts 中的函数在应用中被调用为 components.notifications.lib.send。

认证保留在应用中，因为组件内部无法使用 ctx.auth。
环境变量访问保留在应用中，因为组件函数无法读取 process.env。
将父级应用的 ID 作为字符串传递过边界，因为 Id 类型在面向应用的 ComponentApi 中会变成普通字符串。
不要在组件参数或模式中使用 v.id("parentTable") 来引用应用拥有的数据表，因为组件无法访问应用的数据表命名空间。
从组件自身的 ./_generated/server 导入 query、mutation 和 action，而不是应用的生成文件。
不要将组件函数直接暴露给客户端。当客户端需要访问时，创建应用包装器，因为组件是内部的，需要应用提供的认证/环境变量接入。
如果组件定义了 HTTP 处理器，请在应用的 convex/http.ts 中挂载路由，因为组件无法注册自身的 HTTP 路由。
如果组件需要分页，请使用 convex-helpers 中的 paginator 而不是内置的 .paginate()，因为 .paginate() 无法跨组件边界工作。
为所有公共组件函数添加 args 和 returns 验证器，因为组件边界需要明确的类型契约。

认证和环境变量访问

// 错误：组件代码不能依赖应用的认证或环境变量
const identity = await ctx.auth.getUserIdentity();
const apiKey = process.env.OPENAI_API_KEY;

// 正确：应用解析认证和环境变量，然后传递明确的值
const userId = await getAuthUserId(ctx);
if (!userId) throw new Error("Not authenticated");

await ctx.runAction(components.translator.translate, {
  userId,
  apiKey: process.env.OPENAI_API_KEY,
  text: args.text,
});

面向客户端的 API

// 错误：假设组件函数可以直接被客户端调用
export const send = components.notifications.send;

// 正确：通过应用 mutation 或 query 重新导出
export const sendNotification = mutation({
  args: { message: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) throw new Error("Not authenticated");

    await ctx.runMutation(components.notifications.lib.send, {
      userId,
      message: args.message,
    });
    return null;
  },
});

// 错误：父级应用数据表的 ID 不是有效的组件验证器
args: { userId: v.id("users") }

// 正确：在边界处将父级拥有的 ID 视为字符串
args: { userId: v.string() }

关于更多模式，包括用于回调的函数句柄、从模式推导验证器、使用全局表的静态配置以及基于类的客户端包装器，请参阅 references/advanced-patterns.md。

按此顺序尝试验证：

npx convex codegen --component-dir convex/components/<name>
npx convex codegen
npx convex dev

新仓库在配置 CONVEX_DEPLOYMENT 之前，这些命令可能会失败。
在代码生成运行之前，组件本地的 ./_generated/* 导入和应用侧的 components.<name>... 引用将无法通过类型检查。
如果验证因 Convex 登录或部署设置而阻塞，请停止并询问用户该具体步骤，而不是猜测。

在用户确认目标后，请精确阅读以下文件之一：

references/local-components.md
references/packaged-components.md
references/hybrid-components.md

官方文档：Authoring Components

询问了用户想要构建什么并确认了组件形态
阅读了匹配的参考文件
确认组件是合适的抽象
规划了数据表、公共 API、边界和应用包装器
组件位于 convex/components/<name>/ 下（或发布时的包布局）
组件从其自身的 ./_generated/server 导入
认证、环境变量访问和 HTTP 路由保留在应用中
父级应用的 ID 以 v.string() 形式跨边界传递
公共函数具有 args 和 returns 验证器
运行了 npx convex dev 并修复了代码生成或类型问题

🇺🇸English

Convex Create Component

Create reusable Convex components with clear boundaries and a small app-facing API.

When to Use

Creating a new Convex component in an existing app
Extracting reusable backend logic into a component
Building a third-party integration that should own its own tables and workflows
Packaging Convex functionality for reuse across multiple apps

When Not to Use

One-off business logic that belongs in the main app
Thin utilities that do not need Convex tables or functions
App-level orchestration that should stay in convex/
Cases where a normal TypeScript library is enough

Workflow

Ask the user what they are building and what the end goal is. If the repo already makes the answer obvious, say so and confirm before proceeding.
Choose the shape using the decision tree below and read the matching reference file.
Decide whether a component is justified. Prefer normal app code or a regular library if the feature does not need isolated tables, backend functions, or reusable persistent state.
Make a short plan for:
- what tables the component owns
- what public functions it exposes
- what data must be passed in from the app (auth, env vars, parent IDs)
- what stays in the app as wrappers or HTTP mounts
Create the component structure with convex.config.ts, schema.ts, and function files.
Implement functions using the component's own ./_generated/server imports, not the app's generated files.
Wire the component into the app with app.use(...). If the app does not already have convex/convex.config.ts, create it.
Call the component from the app through components.<name> using ctx.runQuery, ctx.runMutation, or ctx.runAction.
If React clients, HTTP callers, or public APIs need access, create wrapper functions in the app instead of exposing component functions directly.
Run npx convex dev and fix codegen, type, or boundary issues before finishing.

Choose the Shape

Ask the user, then pick one path:

Goal	Shape	Reference
Component for this app only	Local	`references/local-components.md`
Publish or share across apps	Packaged	`references/packaged-components.md`
User explicitly needs local + shared library code	Hybrid	`references/hybrid-components.md`
Not sure	Default to local	`references/local-components.md`

Read exactly one reference file before proceeding.

Default Approach

Unless the user explicitly wants an npm package, default to a local component:

Put it under convex/components/<componentName>/
Define it with defineComponent(...) in its own convex.config.ts
Install it from the app's convex/convex.config.ts with app.use(...)
Let npx convex dev generate the component's own _generated/ files

Component Skeleton

A minimal local component with a table and two functions, plus the app wiring.

// convex/components/notifications/convex.config.ts
import { defineComponent } from "convex/server";

export default defineComponent("notifications");



// convex/components/notifications/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  notifications: defineTable({
    userId: v.string(),
    message: v.string(),
    read: v.boolean(),
  }).index("by_user", ["userId"]),
});



// convex/components/notifications/lib.ts
import { v } from "convex/values";
import { mutation, query } from "./_generated/server.js";

export const send = mutation({
  args: { userId: v.string(), message: v.string() },
  returns: v.id("notifications"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("notifications", {
      userId: args.userId,
      message: args.message,
      read: false,
    });
  },
});

export const listUnread = query({
  args: { userId: v.string() },
  returns: v.array(
    v.object({
      _id: v.id("notifications"),
      _creationTime: v.number(),
      userId: v.string(),
      message: v.string(),
      read: v.boolean(),
    })
  ),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("notifications")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .filter((q) => q.eq(q.field("read"), false))
      .collect();
  },
});



// convex/convex.config.ts
import { defineApp } from "convex/server";
import notifications from "./components/notifications/convex.config.js";

const app = defineApp();
app.use(notifications);

export default app;



// convex/notifications.ts  (app-side wrapper)
import { v } from "convex/values";
import { mutation, query } from "./_generated/server";
import { components } from "./_generated/api";
import { getAuthUserId } from "@convex-dev/auth/server";

export const sendNotification = mutation({
  args: { message: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) throw new Error("Not authenticated");

    await ctx.runMutation(components.notifications.lib.send, {
      userId,
      message: args.message,
    });
    return null;
  },
});

export const myUnread = query({
  args: {},
  handler: async (ctx) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) throw new Error("Not authenticated");

    return await ctx.runQuery(components.notifications.lib.listUnread, {
      userId,
    });
  },
});

Note the reference path shape: a function in convex/components/notifications/lib.ts is called as components.notifications.lib.send from the app.

Critical Rules

Keep authentication in the app, because ctx.auth is not available inside components.
Keep environment access in the app, because component functions cannot read process.env.
Pass parent app IDs across the boundary as strings, because Id types become plain strings in the app-facing ComponentApi.
Do not use v.id("parentTable") for app-owned tables inside component args or schema, because the component has no access to the app's table namespace.
Import query, mutation, and action from the component's own ./_generated/server, not the app's generated files.
Do not expose component functions directly to clients. Create app wrappers when client access is needed, because components are internal and need auth/env wiring the app provides.

Patterns

Authentication and environment access

// Bad: component code cannot rely on app auth or env
const identity = await ctx.auth.getUserIdentity();
const apiKey = process.env.OPENAI_API_KEY;



// Good: the app resolves auth and env, then passes explicit values
const userId = await getAuthUserId(ctx);
if (!userId) throw new Error("Not authenticated");

await ctx.runAction(components.translator.translate, {
  userId,
  apiKey: process.env.OPENAI_API_KEY,
  text: args.text,
});

Client-facing API

// Bad: assuming a component function is directly callable by clients
export const send = components.notifications.send;



// Good: re-export through an app mutation or query
export const sendNotification = mutation({
  args: { message: v.string() },
  returns: v.null(),
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    if (!userId) throw new Error("Not authenticated");

    await ctx.runMutation(components.notifications.lib.send, {
      userId,
      message: args.message,
    });
    return null;
  },
});

IDs across the boundary

// Bad: parent app table IDs are not valid component validators
args: { userId: v.id("users") }



// Good: treat parent-owned IDs as strings at the boundary
args: { userId: v.string() }

Advanced Patterns

For additional patterns including function handles for callbacks, deriving validators from schema, static configuration with a globals table, and class-based client wrappers, see references/advanced-patterns.md.

Validation

Try validation in this order:

npx convex codegen --component-dir convex/components/<name>
npx convex codegen
npx convex dev

Important:

Fresh repos may fail these commands until CONVEX_DEPLOYMENT is configured.
Until codegen runs, component-local ./_generated/* imports and app-side components.<name>... references will not typecheck.
If validation blocks on Convex login or deployment setup, stop and ask the user for that exact step instead of guessing.

Reference Files

Read exactly one of these after the user confirms the goal:

references/local-components.md
references/packaged-components.md
references/hybrid-components.md

Official docs: Authoring Components

Checklist

Asked the user what they want to build and confirmed the shape
Read the matching reference file
Confirmed a component is the right abstraction
Planned tables, public API, boundaries, and app wrappers
Component lives under convex/components/<name>/ (or package layout if publishing)
Component imports from its own ./_generated/server
Auth, env access, and HTTP routes stay in the app
Parent app IDs cross the boundary as v.string()
Public functions have args and returns validators
Ran npx convex dev and fixed codegen or type issues

Weekly Installs

6.7K

Repository

get-convex/agent-skills

GitHub Stars

First Seen

10 days ago

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex6.7K

cursor6.7K

kimi-cli6.7K

amp6.7K

github-copilot6.7K

cline6.7K

If the component defines HTTP handlers, mount the routes in the app's convex/http.ts, because components cannot register their own HTTP routes.

If the component needs pagination, use paginator from convex-helpers instead of built-in .paginate(), because .paginate() does not work across the component boundary.

Add args and returns validators to all public component functions, because the component boundary requires explicit type contracts.

Convex组件创建指南：构建可复用后端模块与第三方集成

🇨🇳中文介绍

Convex Create Component

何时使用

何时不使用

工作流程

相关 Skills

选择组件形态

默认方法

组件骨架

关键规则

模式

认证和环境变量访问

面向客户端的 API

跨边界的 ID

高级模式

验证

参考文件

检查清单

🇺🇸English

Convex Create Component

When to Use

When Not to Use

Workflow

Choose the Shape

Default Approach

Component Skeleton

Critical Rules

Patterns

Authentication and environment access

Client-facing API

IDs across the boundary

Advanced Patterns

Validation

Reference Files

Checklist