# 凸 + Next.js ## 使用此技能 * 在新的或现有的 Next.js 应用程序中使用 Bootstrap Convex。 * 添加端到端的功能：架构、索引、函数、UI 挂钩、身份验证和部署。 * 调试典型的集成失败：缺少提供程序、缺少生成的代码、错误的客户端/服务器边界、缺少环境变量。 * 检查 Convex 是否适合实时或协作 Next.js 功能。 ## 不要使用该技能 * 该任务是简单的 Next.js UI 工作，没有 Convex 依赖性。 * 后端肯定不是Convex，用户也没有考虑迁移。 * 问题是通用数据库理论，没有 Next.js/Convex 实现工作。 ## 默认姿势 * 使用`npx凸开发`进行开发。 * 在客户端组件中保留反应式挂钩。 * 优先使用索引查询而不是`.filter(...)`。 * 默认情况下将无界列表视为分页。 * 将外部I/O放入动作中；仅当需要 Node API 或不受支持的包时才添加“使用节点”。 * 需要对公共函数进行输入验证；添加返回验证，除非有充分的理由不这样做。 * 添加对用户数据的显式身份验证和所有权检查。 * 当重复相同的身份验证/租户检查时，首选辅助函数或自定义包装器。 ## 从存储库开始回答问题 1. 这是一个新应用程序、现有的 Next.js 应用程序还是迁移？ 2. 应用程序路由器、页面路由器或两者兼而有之？ 3. 该功能是否需要反应性、SSR、服务器操作，还是三者兼而有之？ 4. 数据集是有界的还是应该分页？ 5. auth 是否已经存在？如果是，它是仅限客户端还是服务器上也需要？ 6. Convex 组件会使该功能更具可重用性或隔离性吗？ ## 工作流程 1 — 选择正确的起始路径 ### A. 全新项目更喜欢： npm 创建凸@最新如果用户已经拥有想要保留的 Next.js 应用程序结构，请改用路径 B。 ### B. 现有的 Next.js 应用程序安装 Convex 并启动开发同步： npm 安装凸面 npx 凸开发预期成果： * `convex/` 存在，或者来自 `convex.json` 的自定义函数目录 * 生成的文件出现在 `_ generated/` 下 * 开发部署或本地部署已连接 * `NEXT_PUBLIC_CONVEX_URL` 可用于前端请参阅 [references/01-setup-and-decision-tree.md]()。 ## 工作流程 2 — 查询模式的模型数据，而不是屏幕形状在编写UI之前，定义： * 表格 * 所有权字段 * 主要读取所需的索引 * 列表是否有界或分页 * 文件是否应该存放在凸文件存储中而不是大文档中规则： * 与深层嵌套的 blob 相比，更喜欢平面关系型文档。 * 使用 `v.id("table")` 来建立关系。 * 为您知道需要的每个重复过滤/排序路径添加索引。 * 如果查询要扫描无界表，请重新设计索引或对其进行分页。请参阅 [references/02-schema-and-indexes.md]()。 ## 工作流程 3 — 选择正确的凸函数形状 ### 查询用于纯读取。保持它们小、有索引且可预测。 ### 突变用于写入和事务读写逻辑。 ### 行动用于外部 API、长时间运行的工作或非事务性编排。 * 如果“fetch”足够，则保持默认的 Convex 运行时。 * 仅当您需要仅限 Node 的 API 或不受支持的软件包时才添加“使用节点”。 * 带有“use node”的文件应该只包含操作。详细模式：[references/03-functions-and-safety.md]() ## 工作流程 4 — 尽早实施验证、身份验证和所有权对于公共职能： * 定义`args` * 通常定义`returns` * 当函数受保护时调用 `ctx.auth.getUserIdentity()` * 检查所有权或团队成员身份，而不仅仅是身份验证 * 一旦重复开始传播，将重复的检查移至助手或自定义包装器中如果身份验证或租户检查在许多函数中重复，请考虑： * `凸/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 hooks。请参阅 [references/04-nextjs-client-and-server-boundaries.md]()。 ## 工作流程 6 — 将大型列表视为分页问题在以下情况下默认使用分页： * 用户说“全部”、“提要”、“活动”、“历史记录”、“消息”、“通知”、“搜索结果”或“无限滚动” * 表可以增长，没有自然的硬限制 * 否则你会在面向用户的列表上访问 `.collect()` 图案： * 后端查询使用`.paginate(paginationOpts)` * React客户端使用`usePaginatedQuery` 请参阅 [references/06-pagination-performance-and-realtime.md]()。 ## 工作流程 7 — 当功能需要隔离时考虑组件当具有以下特征时，凸组件通常是值得的： * 有自己的架构、功能和内部作业 * 应该可以跨应用程序重复使用 * 否则会用紧密耦合的代码污染根“凸/”文件夹当功能较小且特定于一个应用程序时，请使用普通应用程序代码。请参阅 [references/07-components-migrations-and-reuse.md]()。 ## 工作流程 8 — 选择正确的开发模式 * 在您自己的计算机或本地编码代理中，标准“npx 凸开发”通常是正确的。 * 在无法登录的远程或后台代理中，使用代理模式。 * 对于隔离的本地开发，请使用本地部署。请参阅 [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 。 --严格 python {baseDir}/scripts/validate_project.py --root 。 --json 验证器会检查该技能旨在捕获的常见故障： * 缺少 Convex 安装或生成的代码 * 缺少提供商或环境接线 * 非客户端组件中的钩子使用 * 隐式表访问 * 查询中的 `.collect()` 或 `.filter()` 味道 * 凸函数缺少验证器 * 有风险的“使用节点”文件混合 * 针对公共功能的调度程序调用 * 缺少 TypeScript 严格性或缺少 Convex ESLint 插件 ## 工作流程 10 — 干净部署正常开发过程中，继续使用： npx 凸开发对于生产或 CI： npx 凸部署对于 Vercel 构建，常见模式是： npx 凸部署--cmd“npm run build” 请参阅 [references/09-deploy-ci-and-vercel.md]()。 ## 强大的最终实现通常包括哪些内容 *更新了“凸/schema.ts” * 新的或更新的索引 *带有“args”和通常“returns”的公共函数 * 需要时进行授权或所有权检查 * 通过生成的`api`连接UI * 仅在实际需要的地方`“使用客户端” * 分页列表而不是无界集合 * 关于所需环境变量的注释 * 用户应运行的命令来验证更改 ## 更改代码时首选的响应形状 1. 注明要添加或编辑的文件。 2. 用一句话解释架构选择。 3. 应用代码更改。 4. 运行验证器或描述要运行的确切检查。 5. 提出任何后续环境变量、身份验证设置、部署步骤或迁移问题。 ## 参考图 * 设置并选择路径：[references/01-setup-and-decision-tree.md]() * 模式和索引设计：[references/02-schema-and-indexes.md]() * 函数、验证、节点操作、调度程序安全：[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]() * 本地开发、代理模式和本地部署：[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]()

凸Nextjs

包含技能