convex-nextjs

Convex + Next.js

适用场景

• 在新的或现有的 Next.js 应用中初始化 Convex。
• 端到端添加一项功能：包括架构、索引、函数、UI hooks、身份验证和部署。
• 调试常见的集成故障：缺少 provider、缺少生成代码、客户端／服务端边界错误、缺少环境变量。
• 评估 Convex 是否适合 Next.js 中的实时功能或协作功能。

不适用场景

• 任务只是普通的 Next.js UI 开发，不依赖 Convex。
• 后端明确不是 Convex，且用户没有考虑迁移。
• 问题是通用的数据库理论问题，不涉及 Next.js／Convex 实现。

默认做法

• 使用 npx convex dev 进行开发。
• 在客户端组件中使用响应式 hooks。
• 优先使用索引查询，而不是 .filter(...)。
• 默认将无界列表视为需要分页的列表。
• 将外部 I/O 放在 actions 中；只有在需要 Node API 或不受支持的包时，才添加 "use node"。
• 要求公开函数进行输入验证；除非有充分理由，否则也要添加返回值验证。
• 对用户数据添加明确的身份验证和所有权检查。
• 如果重复出现相同的身份验证／租户检查，优先使用辅助函数或自定义封装。

根据代码库需要回答的初始问题

1. 这是新应用、现有 Next.js 应用，还是迁移？
2. 使用 App Router、Pages Router，还是两者都使用？
3. 此功能需要响应式、SSR、服务端操作，还是三者都需要？
4. 数据集有界吗？还是需要分页？
5. 是否已具备身份验证？如果有，是仅在客户端使用，还是服务端也需要？
6. 使用 Convex 组件能否让此功能更易于复用或隔离？

工作流 1 — 选择合适的起步路径

A. 全新项目

优先使用：

npm create convex@latest

如果用户已有想要保留结构的 Next.js 应用，请改用路径 B。

B. 现有 Next.js 应用

安装 Convex 并启动开发同步：

npm install convex
npx convex dev

预期结果：

• 存在 convex/，或存在 convex.json 中指定的自定义函数目录
• 生成的文件出现在 _generated/ 下
• 已连接开发部署或本地部署
• 前端可以使用 NEXT_PUBLIC_CONVEX_URL

请参阅 references/01-setup-and-decision-tree.md。

工作流 2 — 根据查询模式而非页面形态建模数据

编写 UI 前，先定义：

• 表
• 所有权字段
• 主要读取操作所需的索引
• 列表是否有界，或是否需要分页
• 文件是否应该存储在 Convex File Storage 中，而不是大型文档中

规则：

• 优先使用扁平的关系型文档，而不是深层嵌套的数据块。
• 使用 v.id("table") 表示关联关系。
• 为已知的每条重复筛选／排序路径添加索引。
• 如果查询会扫描无界表，请重新设计索引或进行分页。

请参阅 references/02-schema-and-indexes.md。

工作流 3 — 选择正确的 Convex 函数类型

Query

用于纯读取操作。保持函数简短、使用索引且行为可预测。

Mutation

用于写入和事务性读写逻辑。

Action

用于外部 API、长时间运行的工作或非事务性编排。

• 如果 fetch 足以满足需求，请使用默认的 Convex 运行时。
• 只有在需要 Node 专用 API 或不受支持的包时，才添加 "use node"。
• 带有 "use node" 的文件中只能包含 actions。

详细模式请参阅：references/03-functions-and-safety.md

工作流 4 — 尽早落实验证、身份验证和所有权检查

对于公共函数：

• 定义 args
• 通常定义 returns
• 如果函数受保护，则调用 ctx.auth.getUserIdentity()
• 检查所有权或团队成员身份，而不只是身份验证
• 重复检查开始蔓延后，将其移入辅助函数或自定义包装器

如果许多函数中重复出现身份验证或租户检查，可考虑：

• convex/lib/auth.ts 辅助函数
• 用于 query、mutation 或 action 的轻量包装器／自定义函数
• 用于租户／资源检查的共享策略辅助函数

请参阅 references/05-auth-and-access-control.md。

工作流 5 — 遵守 Next.js 边界

• useQuery、useMutation、useAction、usePaginatedQuery 和 usePreloadedQuery 应在客户端组件中使用。
• 对于优先采用响应式数据且需要良好首屏呈现的页面，请在服务端组件中使用 preloadQuery，并在客户端组件中使用 usePreloadedQuery。
• 对于仅在服务端执行的读取，请使用 fetchQuery。
• 对于服务端操作或路由处理程序，请使用 fetchMutation 或 fetchAction。

不要在服务端组件中调用 React 钩子。

请参阅 references/04-nextjs-client-and-server-boundaries.md。

工作流 6 — 将大型列表视为分页问题

在以下情况下，默认使用分页：

• 用户提到“全部”“动态”“活动”“历史记录”“消息”“通知”“搜索结果”或“无限滚动”
• 表格可能持续增长，没有自然的硬性上限
• 否则你会考虑对面向用户的列表使用 .collect()

模式：

• 后端查询使用 .paginate(paginationOpts)
• React 客户端使用 usePaginatedQuery

请参阅 references/06-pagination-performance-and-realtime.md。

工作流 7 — 当功能需要隔离时，考虑使用组件

如果功能具有以下特点，Convex 组件通常值得采用：

• 拥有自己的架构、函数和内部任务
• 应能在多个应用间复用
• 否则会让紧密耦合的代码充斥根目录 convex/

如果功能规模较小且仅针对单个应用，请使用常规应用代码。

请参阅 references/07-components-migrations-and-reuse.md。

工作流 8 — 选择合适的开发模式

• 在自己的机器上或本地编码 Agent 中，通常使用标准的 npx convex dev。
• 在无法登录的远程或后台 Agent 中，使用 Agent Mode。
• 对于隔离的纯本地开发，使用本地部署。

请参阅 references/08-local-dev-agent-mode-and-cloud-agents.md。

工作流 9 — 停止前进行验证

运行：

python {baseDir}/scripts/validate_project.py --root .

实用标志：

python {baseDir}/scripts/validate_project.py --root . --strict
python {baseDir}/scripts/validate_project.py --root . --json

验证器会检查此技能旨在捕获的常见问题：

• 缺少 Convex 安装或生成的代码
• 缺少 provider 或环境变量配置
• 在非客户端组件中使用钩子
• 隐式访问表
• 查询中存在 .collect() 或 .filter() 的可疑用法
• Convex 函数缺少验证器
• 存在风险的 "use node" 文件混用
• 调度器调用指向公共函数
• 缺少 TypeScript 严格性配置或 Convex ESLint 插件

工作流 10 — 干净地部署

日常开发期间，继续使用：

npx convex dev

用于生产环境或 CI：

npx convex deploy

对于 Vercel 构建，常见模式是：

npx convex deploy --cmd "npm run build"

请参阅 references/09-deploy-ci-and-vercel.md。

出色的最终实现通常包含

• 更新后的 convex/schema.ts
• 新建或更新的索引
• 带有 args 且通常带有 returns 的公共函数
• 必要时进行身份验证或所有权检查
• 通过生成的 api 接入 UI
• 仅在确有需要的地方使用 "use client"
• 使用分页列表而非无界收集
• 关于所需环境变量的说明
• 用户应运行以验证更改的命令

进行代码更改时优先采用的回复结构

1. 说明要添加或编辑的文件。
2. 用一句话解释架构选择。
3. 应用代码更改。
4. 运行验证器，或说明要运行的确切检查。
5. 指出后续需要设置的环境变量、身份验证、部署步骤或迁移注意事项。

参考索引

• 设置和路径选择：references/01-setup-and-decision-tree.md
• 架构和索引设计：references/02-schema-and-indexes.md
• 函数、验证、Node 操作和调度器安全：references/03-functions-and-safety.md
• Next.js 客户端/服务端边界和 SSR：references/04-nextjs-client-and-server-boundaries.md
• 身份验证和访问控制：references/05-auth-and-access-control.md
• 分页、性能和实时功能：references/06-pagination-performance-and-realtime.md
• 组件、迁移和复用：references/07-components-migrations-and-reuse.md
• 本地开发、Agent Mode 和本地部署：references/08-local-dev-agent-mode-and-cloud-agents.md
• 部署和 CI：references/09-deploy-ci-and-vercel.md
• 故障排除和冒烟测试：references/10-troubleshooting-and-smoke-tests.md