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.
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.
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.
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?
Workflow 1 — Choose the right starting path
A. Brand new project
Prefer:
npm create convex@latest
If the user already has a Next.js app structure they want to keep, use path B instead.
B. Existing Next.js app
Install Convex and start dev sync:
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.
Workflow 2 — Model data for query patterns, not screen shapes
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.
Workflow 3 — Pick the correct Convex function shape
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
Workflow 4 — Enforce validation, auth, and ownership early
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.
Workflow 5 — Respect Next.js boundaries
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.
Workflow 6 — Treat large lists as a pagination problem
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.
Workflow 7 — Consider components when the feature wants isolation
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.
Workflow 8 — Choose the right development mode
- 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.
Workflow 9 — Validate before you stop
Run:
python {baseDir}/scripts/validate_project.py --root .
Useful flags:
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
Workflow 10 — Deploy cleanly
During normal development, keep using:
npx convex dev
For production or CI:
npx convex deploy
For Vercel builds, the common pattern is:
npx convex deploy --cmd "npm run build"
See 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
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
1---
2name: convex-nextjs
3description: >-
4 Build, refactor, debug, or review a Convex backend inside a Next.js app. Use
5 when the user mentions Convex, `convex/nextjs`, `npx convex dev`,
6 `NEXT_PUBLIC_CONVEX_URL`, `useQuery`, `useMutation`, `usePaginatedQuery`,
7 schema/indexes, auth, App Router server components/actions, realtime data,
8 chat, notifications, collaborative features, or deploying Convex with
9 Vercel. Also use when deciding whether Convex is a good fit for a Next.js app
10 that needs reactive shared state. Do not use for generic frontend-only
11 Next.js work or non-Convex backends unless the task is specifically about
12 adopting, migrating to, or evaluating Convex.
13compatibility: >-
14 Best for Next.js 13+ with the App Router and TypeScript, but works for Pages
15 Router and mixed repos too. Assumes the Convex CLI is available via the
16 `convex` npm package and the repo can run `npx convex ...`.
17metadata:
18 source: https://skillmd.com/skills/tristanmanchester/convex-nextjs
19 version: 2.0.0
20 ecosystem: convex
21 framework: nextjs
22 focus:
23 - progressive-disclosure
24 - validation-first
25 - realtime
26 - current-convex-patterns
27---
28
29# Convex + Next.js
30
31## Use this skill to
32- Bootstrap Convex in a new or existing Next.js app.
33- Add a feature end to end: schema, indexes, functions, UI hooks, auth, and deployment.
34- Debug typical integration failures: missing provider, missing generated code, bad client/server boundaries, missing env vars.
35- Review whether Convex is a good fit for a realtime or collaborative Next.js feature.
36
37## Do not use this skill when
38- The task is plain Next.js UI work with no Convex dependency.
39- The backend is definitely not Convex and the user is not considering migration.
40- The problem is generic database theory with no Next.js/Convex implementation work.
41
42## Default posture
43- Use `npx convex dev` for development.
44- Keep reactive hooks in Client Components.
45- Prefer indexed queries over `.filter(...)`.
46- Treat unbounded lists as paginated by default.
47- Put external I/O in actions; add `"use node"` only if Node APIs or unsupported packages are required.
48- Require input validation on public functions; add return validation unless there is a good reason not to.
49- Add explicit auth and ownership checks for user data.
50- Prefer helper functions or custom wrappers when the same auth/tenant checks repeat.
51
52## Starting questions to answer from the repo
531. Is this a new app, an existing Next.js app, or a migration?
542. App Router, Pages Router, or both?
553. Does the feature need reactivity, SSR, server actions, or all three?
564. Is the dataset bounded or should it paginate?
575. Is auth already present? If yes, is it client-only or needed on the server too?
586. Would a Convex component make this feature more reusable or isolated?
59
60## Workflow 1 — Choose the right starting path
61
62### A. Brand new project
63Prefer:
64```bash
65npm create convex@latest
66```
67
68If the user already has a Next.js app structure they want to keep, use path B instead.
69
70### B. Existing Next.js app
71Install Convex and start dev sync:
72```bash
73npm install convex
74npx convex dev
75```
76
77Expected outcomes:
78- `convex/` exists, or the custom functions directory from `convex.json`
79- generated files appear under `_generated/`
80- a dev deployment or local deployment is connected
81- `NEXT_PUBLIC_CONVEX_URL` is available for the frontend
82
83See [references/01-setup-and-decision-tree.md](references/01-setup-and-decision-tree.md).
84
85## Workflow 2 — Model data for query patterns, not screen shapes
86Before writing UI, define:
87- the tables
88- the ownership fields
89- the indexes needed for the main reads
90- whether lists are bounded or paginated
91- whether files should live in Convex File Storage instead of large documents
92
93Rules:
94- Prefer flat relational-style documents over deep nested blobs.
95- Use `v.id("table")` for relationships.
96- Add indexes for every repeated filter/sort path you know you need.
97- If the query would scan an unbounded table, redesign the index or paginate it.
98
99See [references/02-schema-and-indexes.md](references/02-schema-and-indexes.md).
100
101## Workflow 3 — Pick the correct Convex function shape
102
103### Query
104Use for pure reads. Keep them small, indexed, and predictable.
105
106### Mutation
107Use for writes and transactional read-write logic.
108
109### Action
110Use for external APIs, long-running work, or non-transactional orchestration.
111- Stay in the default Convex runtime if `fetch` is enough.
112- Add `"use node"` only when you need Node-only APIs or unsupported packages.
113- Files with `"use node"` should contain actions only.
114
115Detailed patterns: [references/03-functions-and-safety.md](references/03-functions-and-safety.md)
116
117## Workflow 4 — Enforce validation, auth, and ownership early
118For public functions:
119- define `args`
120- usually define `returns`
121- call `ctx.auth.getUserIdentity()` when the function is protected
122- check ownership or team membership, not just authentication
123- move repeated checks into helpers or custom wrappers once duplication starts to spread
124
125If auth or tenant checks repeat in many functions, consider:
126- `convex/lib/auth.ts` helpers
127- thin wrappers/custom functions for `query`, `mutation`, or `action`
128- shared policy helpers for tenant/resource checks
129
130See [references/05-auth-and-access-control.md](references/05-auth-and-access-control.md).
131
132## Workflow 5 — Respect Next.js boundaries
133- `useQuery`, `useMutation`, `useAction`, `usePaginatedQuery`, and `usePreloadedQuery` belong in Client Components.
134- For reactive-first pages with good first paint, use `preloadQuery` in a Server Component and `usePreloadedQuery` in a Client Component.
135- For server-only reads, use `fetchQuery`.
136- For Server Actions or Route Handlers, use `fetchMutation` or `fetchAction`.
137
138Do not call React hooks from Server Components.
139
140See [references/04-nextjs-client-and-server-boundaries.md](references/04-nextjs-client-and-server-boundaries.md).
141
142## Workflow 6 — Treat large lists as a pagination problem
143Use pagination by default when:
144- the user says “all”, “feed”, “activity”, “history”, “messages”, “notifications”, “search results”, or “infinite scroll”
145- the table can grow without a natural hard limit
146- you would otherwise reach for `.collect()` on a user-facing list
147
148Pattern:
149- backend query uses `.paginate(paginationOpts)`
150- React client uses `usePaginatedQuery`
151
152See [references/06-pagination-performance-and-realtime.md](references/06-pagination-performance-and-realtime.md).
153
154## Workflow 7 — Consider components when the feature wants isolation
155A Convex component is often worth it when the feature:
156- has its own schema, functions, and internal jobs
157- should be reusable across apps
158- would otherwise pollute the root `convex/` folder with tightly-coupled code
159
160Use normal app code when the feature is small and specific to one app.
161
162See [references/07-components-migrations-and-reuse.md](references/07-components-migrations-and-reuse.md).
163
164## Workflow 8 — Choose the right development mode
165- On your own machine or in a local coding agent, standard `npx convex dev` is usually right.
166- In remote or background agents that cannot log in, use Agent Mode.
167- For isolated local-only development, use local deployments.
168
169See [references/08-local-dev-agent-mode-and-cloud-agents.md](references/08-local-dev-agent-mode-and-cloud-agents.md).
170
171## Workflow 9 — Validate before you stop
172Run:
173```bash
174python {baseDir}/scripts/validate_project.py --root .
175```
176
177Useful flags:
178```bash
179python {baseDir}/scripts/validate_project.py --root . --strict
180python {baseDir}/scripts/validate_project.py --root . --json
181```
182
183The validator checks for the common failures this skill is designed to catch:
184- missing Convex installation or generated code
185- missing provider or env wiring
186- hook usage in non-client components
187- implicit table access
188- `.collect()` or `.filter()` smells in queries
189- missing validators on Convex functions
190- risky `"use node"` file mixes
191- scheduler calls aimed at public functions
192- missing TypeScript strictness or missing Convex ESLint plugin
193
194## Workflow 10 — Deploy cleanly
195During normal development, keep using:
196```bash
197npx convex dev
198```
199
200For production or CI:
201```bash
202npx convex deploy
203```
204
205For Vercel builds, the common pattern is:
206```bash
207npx convex deploy --cmd "npm run build"
208```
209
210See [references/09-deploy-ci-and-vercel.md](references/09-deploy-ci-and-vercel.md).
211
212## What a strong final implementation usually includes
213- updated `convex/schema.ts`
214- new or updated indexes
215- public functions with `args` and usually `returns`
216- auth or ownership checks where needed
217- UI wired through the generated `api`
218- `"use client"` only where it is actually needed
219- paginated lists instead of unbounded collects
220- a note about required env vars
221- commands the user should run to verify the change
222
223## Response shape to prefer when making code changes
2241. State the files to add or edit.
2252. Explain the architectural choice in one sentence.
2263. Apply the code changes.
2274. Run the validator or describe the exact checks to run.
2285. Call out any follow-up env vars, auth setup, deploy steps, or migration concerns.
229
230## Reference map
231- Setup and choosing a path: [references/01-setup-and-decision-tree.md](references/01-setup-and-decision-tree.md)
232- Schema and index design: [references/02-schema-and-indexes.md](references/02-schema-and-indexes.md)
233- Functions, validation, Node actions, scheduler safety: [references/03-functions-and-safety.md](references/03-functions-and-safety.md)
234- Next.js client/server boundaries and SSR: [references/04-nextjs-client-and-server-boundaries.md](references/04-nextjs-client-and-server-boundaries.md)
235- Auth and access control: [references/05-auth-and-access-control.md](references/05-auth-and-access-control.md)
236- Pagination, performance, and realtime: [references/06-pagination-performance-and-realtime.md](references/06-pagination-performance-and-realtime.md)
237- Components, migrations, and reuse: [references/07-components-migrations-and-reuse.md](references/07-components-migrations-and-reuse.md)
238- Local dev, Agent Mode, and local deployments: [references/08-local-dev-agent-mode-and-cloud-agents.md](references/08-local-dev-agent-mode-and-cloud-agents.md)
239- Deploy and CI: [references/09-deploy-ci-and-vercel.md](references/09-deploy-ci-and-vercel.md)
240- Troubleshooting and smoke tests: [references/10-troubleshooting-and-smoke-tests.md](references/10-troubleshooting-and-smoke-tests.md)