convex-nextjs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex + Next.js

Use this skill to

本技能适用场景

Bootstrap Convex in a new or existing Next.js app.
Add a feature end to end: schema, indexes, functions, UI hooks, auth, and deployment.
Debug typical integration failures: missing provider, missing generated code, bad client/server boundaries, missing env vars.
Review whether Convex is a good fit for a realtime or collaborative Next.js feature.

在新的或已有的Next.js应用中快速搭建Convex。
端到端添加功能：schema、索引、函数、UI钩子、认证及部署。
调试典型集成故障：缺失提供者、缺失生成代码、客户端/服务端边界错误、缺失环境变量。
评审Convex是否适合Next.js应用的实时或协作类功能。

Do not use this skill when

本技能不适用场景

The task is plain Next.js UI work with no Convex dependency.
The backend is definitely not Convex and the user is not considering migration.
The problem is generic database theory with no Next.js/Convex implementation work.

任务仅为无Convex依赖的纯Next.js UI开发。
后端明确非Convex且用户不考虑迁移。
问题为通用数据库理论，无Next.js/Convex落地开发需求。

Default posture

默认实践准则

Use
```
npx convex dev
```
for development.
Keep reactive hooks in Client Components.
Prefer indexed queries over
```
.filter(...)
```
.
Treat unbounded lists as paginated by default.
Put external I/O in actions; add
```
"use node"
```
only if Node APIs or unsupported packages are required.
Require input validation on public functions; add return validation unless there is a good reason not to.
Add explicit auth and ownership checks for user data.
Prefer helper functions or custom wrappers when the same auth/tenant checks repeat.

开发阶段使用
```
npx convex dev
```
。
将响应式钩子放在Client Components中。
优先使用索引查询而非
```
.filter(...)
```
。
默认将无边界列表视为分页列表。
将外部I/O放在actions中；仅当需要Node API或不支持的包时才添加
```
"use node"
```
。
公共函数需添加输入验证；除非有充分理由，否则添加返回验证。
为用户数据添加明确的认证和所有权校验。
当相同的认证/租户校验重复出现时，优先使用辅助函数或自定义封装。

Starting questions to answer from the repo

从仓库入手需明确的问题

Is this a new app, an existing Next.js app, or a migration?
App Router, Pages Router, or both?
Does the feature need reactivity, SSR, server actions, or all three?
Is the dataset bounded or should it paginate?
Is auth already present? If yes, is it client-only or needed on the server too?
Would a Convex component make this feature more reusable or isolated?

这是新项目、已有Next.js应用还是迁移项目？
使用App Router、Pages Router还是两者兼用？
功能是否需要响应性、SSR、server actions或三者兼具？
数据集是有界的还是需要分页？
是否已存在认证？若存在，是仅客户端认证还是服务端也需要？
Convex组件是否能让该功能更具复用性或隔离性？

Workflow 1 — Choose the right starting path

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

A. Brand new project

A. 全新项目

Prefer:

bash

npm create convex@latest

If the user already has a Next.js app structure they want to keep, use path B instead.

优先选择：

bash

npm create convex@latest

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

B. Existing Next.js app

B. 已有Next.js应用

Install Convex and start dev sync:

bash

npm install convex
npx convex dev

Expected outcomes:

```
convex/
```
exists, or the custom functions directory from
```
convex.json
```
generated files appear under
```
_generated/
```
a dev deployment or local deployment is connected
```
NEXT_PUBLIC_CONVEX_URL
```
is available for the frontend

See references/01-setup-and-decision-tree.md.

安装Convex并启动开发同步：

bash

npm install convex
npx convex dev

预期结果：

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

详见references/01-setup-and-decision-tree.md。

Workflow 2 — Model data for query patterns, not screen shapes

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

Before writing UI, define:

the tables
the ownership fields
the indexes needed for the main reads
whether lists are bounded or paginated
whether files should live in Convex File Storage instead of large documents

Rules:

Prefer flat relational-style documents over deep nested blobs.
Use
```
v.id("table")
```
for relationships.
Add indexes for every repeated filter/sort path you know you need.
If the query would scan an unbounded table, redesign the index or paginate it.

See references/02-schema-and-indexes.md.

编写UI前，先定义：

数据表
所有权字段
主查询所需的索引
列表是有界的还是需要分页
文件是否应存储在Convex File Storage而非大型文档中

规则：

优先使用扁平的关系型文档而非深度嵌套的二进制大对象。
使用
```
v.id("table")
```
建立关联。
为所有已知需要重复过滤/排序的路径添加索引。
如果查询会扫描无边界数据表，请重新设计索引或进行分页。

详见references/02-schema-and-indexes.md。

Workflow 3 — Pick the correct Convex function shape

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

Query

Use for pure reads. Keep them small, indexed, and predictable.

用于纯读取操作。保持函数精简、带索引且可预测。

Mutation

Use for writes and transactional read-write logic.

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

Action

Use for external APIs, long-running work, or non-transactional orchestration.

Stay in the default Convex runtime if
```
fetch
```
is enough.
Add
```
"use node"
```
only when you need Node-only APIs or unsupported packages.
Files with
```
"use node"
```
should contain actions only.

Detailed patterns: references/03-functions-and-safety.md

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

如果
```
fetch
```
足够满足需求，使用默认Convex运行时。
仅当需要Node专属API或不支持的包时才添加
```
"use node"
```
。
包含
```
"use node"
```
的文件应仅存放actions。

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

Workflow 4 — Enforce validation, auth, and ownership early

工作流4 — 尽早实施验证、认证和所有权校验

For public functions:

define
```
args
```
usually define
```
returns
```
call
```
ctx.auth.getUserIdentity()
```
when the function is protected
check ownership or team membership, not just authentication
move repeated checks into helpers or custom wrappers once duplication starts to spread

If auth or tenant checks repeat in many functions, consider:

```
convex/lib/auth.ts
```
helpers
thin wrappers/custom functions for
```
query
```
,
```
mutation
```
, or
```
action
```
shared policy helpers for tenant/resource checks

See references/05-auth-and-access-control.md.

对于公共函数：

定义
```
args
```
通常需定义
```
returns
```
当函数受保护时调用
```
ctx.auth.getUserIdentity()
```
校验所有权或团队成员身份，而非仅校验认证状态
当重复校验开始出现时，将其移至辅助函数或自定义封装中

如果认证或租户校验在多个函数中重复出现，可考虑：

```
convex/lib/auth.ts
```
辅助函数
为
```
query
```
、
```
mutation
```
或
```
action
```
编写轻量封装/自定义函数
用于租户/资源校验的共享策略辅助函数

详见references/05-auth-and-access-control.md。

Workflow 5 — Respect Next.js boundaries

工作流5 — 遵循Next.js边界规则

useQuery

useMutation

useAction

usePaginatedQuery

, and

usePreloadedQuery

belong in Client Components.

For reactive-first pages with good first paint, use
```
preloadQuery
```
in a Server Component and
```
usePreloadedQuery
```
in a Client Component.
For server-only reads, use
```
fetchQuery
```
.
For Server Actions or Route Handlers, use
```
fetchMutation
```
or
```
fetchAction
```
.

Do not call React hooks from Server Components.

See references/04-nextjs-client-and-server-boundaries.md.

useQuery

、

useMutation

、

useAction

、

usePaginatedQuery

和

usePreloadedQuery

应放在Client Components中。

对于优先响应式且首屏性能良好的页面，在Server Component中使用
```
preloadQuery
```
，在Client Component中使用
```
usePreloadedQuery
```
。
对于仅服务端读取操作，使用
```
fetchQuery
```
。
对于Server Actions或路由处理器，使用
```
fetchMutation
```
或
```
fetchAction
```
。

请勿在Server Components中调用React钩子。

详见references/04-nextjs-client-and-server-boundaries.md。

Workflow 6 — Treat large lists as a pagination problem

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

Use pagination by default when:

the user says “all”, “feed”, “activity”, “history”, “messages”, “notifications”, “search results”, or “infinite scroll”
the table can grow without a natural hard limit
you would otherwise reach for
```
.collect()
```
on a user-facing list

Pattern:

backend query uses
```
.paginate(paginationOpts)
```
React client uses
```
usePaginatedQuery
```

See references/06-pagination-performance-and-realtime.md.

默认使用分页的场景：

用户提及“全部”“信息流”“活动”“历史记录”“消息”“通知”“搜索结果”或“无限滚动”
数据表可能无自然上限地增长
否则会在面向用户的列表中使用
```
.collect()
```

模式：

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

详见references/06-pagination-performance-and-realtime.md。

Workflow 7 — Consider components when the feature wants isolation

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

A Convex component is often worth it when the feature:

has its own schema, functions, and internal jobs
should be reusable across apps
would otherwise pollute the root
```
convex/
```
folder with tightly-coupled code

Use normal app code when the feature is small and specific to one app.

See references/07-components-migrations-and-reuse.md.

当功能满足以下条件时，使用Convex组件通常是值得的：

拥有独立的schema、函数和内部任务
需在多个应用间复用
否则会将紧耦合代码污染根目录
```
convex/
```

当功能较小且仅针对单个应用时，使用常规应用代码即可。

详见references/07-components-migrations-and-reuse.md。

Workflow 8 — Choose the right development mode

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

On your own machine or in a local coding agent, standard
```
npx convex dev
```
is usually right.
In remote or background agents that cannot log in, use Agent Mode.
For isolated local-only development, use local deployments.

See references/08-local-dev-agent-mode-and-cloud-agents.md.

在本地机器或本地编码代理中，通常使用标准的
```
npx convex dev
```
即可。
在无法登录的远程或后台代理中，使用Agent Mode。
如需隔离的纯本地开发，使用本地部署。

详见references/08-local-dev-agent-mode-and-cloud-agents.md。

Workflow 9 — Validate before you stop

工作流9 — 完成前进行验证

Run:

bash

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

Useful flags:

bash

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

The validator checks for the common failures this skill is designed to catch:

missing Convex installation or generated code
missing provider or env wiring
hook usage in non-client components
implicit table access
```
.collect()
```
or
```
.filter()
```
smells in queries
missing validators on Convex functions
risky
```
"use node"
```
file mixes
scheduler calls aimed at public functions
missing TypeScript strictness or missing Convex ESLint plugin

运行：

bash

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

实用参数：

bash

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

验证器会检查本技能旨在解决的常见问题：

缺失Convex安装或生成代码
缺失提供者或环境变量配置
在非客户端组件中使用钩子
隐式数据表访问
查询中存在
```
.collect()
```
或
```
.filter()
```
的不良用法
Convex函数缺失验证器
存在风险的
```
"use node"
```
文件混合
针对公共函数的调度器调用
缺失TypeScript严格模式或Convex ESLint插件

Workflow 10 — Deploy cleanly

工作流10 — 干净部署

During normal development, keep using:

bash

npx convex dev

For production or CI:

bash

npx convex deploy

For Vercel builds, the common pattern is:

bash

npx convex deploy --cmd "npm run build"

See references/09-deploy-ci-and-vercel.md.

常规开发阶段，持续使用：

bash

npx convex dev

生产环境或CI环境：

bash

npx convex deploy

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

bash

npx convex deploy --cmd "npm run build"

详见references/09-deploy-ci-and-vercel.md。

What a strong final implementation usually includes

优质最终实现通常包含的内容

updated
```
convex/schema.ts
```
new or updated indexes
public functions with
```
args
```
and usually
```
returns
```
auth or ownership checks where needed
UI wired through the generated
```
api
```
```
"use client"
```
only where it is actually needed
paginated lists instead of unbounded collects
a note about required env vars
commands the user should run to verify the change

更新后的
```
convex/schema.ts
```
新增或更新的索引
带有
```
args
```
且通常带有
```
returns
```
的公共函数
必要的认证或所有权校验
通过生成的
```
api
```
连接的UI
仅在实际需要的地方添加
```
"use client"
```
分页列表而非无边界的collect操作
关于所需环境变量的说明
用户应运行以验证变更的命令

Response shape to prefer when making code changes

代码变更时推荐的响应格式

State the files to add or edit.
Explain the architectural choice in one sentence.
Apply the code changes.
Run the validator or describe the exact checks to run.
Call out any follow-up env vars, auth setup, deploy steps, or migration concerns.

说明需添加或编辑的文件。
用一句话解释架构选择。
应用代码变更。
运行验证器或描述需执行的具体检查。
指出后续需要的环境变量、认证设置、部署步骤或迁移注意事项。

Reference map

参考文档映射

Setup and choosing a path: references/01-setup-and-decision-tree.md
Schema and index design: references/02-schema-and-indexes.md
Functions, validation, Node actions, scheduler safety: references/03-functions-and-safety.md
Next.js client/server boundaries and SSR: references/04-nextjs-client-and-server-boundaries.md
Auth and access control: references/05-auth-and-access-control.md
Pagination, performance, and realtime: references/06-pagination-performance-and-realtime.md
Components, migrations, and reuse: references/07-components-migrations-and-reuse.md
Local dev, Agent Mode, and local deployments: references/08-local-dev-agent-mode-and-cloud-agents.md
Deploy and CI: references/09-deploy-ci-and-vercel.md
Troubleshooting and smoke tests: references/10-troubleshooting-and-smoke-tests.md

安装与路径选择：references/01-setup-and-decision-tree.md
Schema与索引设计：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