1---
2name: convex-core
3description: |-
4 Build Convex schemas, queries, mutations, actions, and client usage with strict validators and indexes.
5 Use for data modeling, function authoring, argument/return validation, and performance guidance.
6 Use proactively when work touches convex/schema.ts, functions, or api.* references.
7
8 Examples:
9 - user: "Design tables for multi-tenant app" → defineSchema/defineTable with indexes
10 - user: "Write a mutation" → args/returns validators + auth checks
11 - user: "Optimize query" → add index and withIndex range expression
12 - user: "Use useQuery" → show generated hook usage
13metadata:
14 source: https://skillmd.com/skills/igorwarzocha/convex-core
15---
16
17<overview>
18Core Convex modeling and function authoring patterns. This skill is the default baseline for Convex work.
19</overview>
20
21<reference>
22- **Schemas**: https://docs.convex.dev/database/schemas
23- **Reading data + indexes**: https://docs.convex.dev/database/reading-data/indexes
24- **Validation**: https://docs.convex.dev/functions/validation
25- **Functions**: https://docs.convex.dev/functions
26- **Pagination**: https://docs.convex.dev/database/pagination
27- **System tables**: https://docs.convex.dev/database/advanced/system-tables
28</reference>
29
30<context name="Core Concepts">
31- Schema: `defineSchema`/`defineTable` in `convex/schema.ts`; use `v` validators.
32- Options: `schemaValidation: false` disables runtime validation; `strictTableNameTypes: false` allows undeclared tables in TS types.
33- Validation: `args`/`returns` validators for queries/mutations/actions; objects reject extra props; `undefined` is invalid (use `null`).
34- Discriminated Unions: Use `v.union` and `v.literal` with `as const` for type-safe state/kind definitions.
35- Types: Use `v.int64()` for 64-bit integers (not `v.bigint()`); `v.null()` for explicit null returns.
36- IDs: Use `Id<"table">` and `v.id("table")` instead of raw strings.
37- Records: `v.record(keys, values)` keys MUST be ASCII, non-empty, and NOT start with `_` or `$`.
38- Validator composition: `Infer`, `.pick`, `.omit`, `.extend`, `.partial` on object validators.
39</context>
40
41<rules>
42
43### Schema Rules
44- You MUST define all tables in `convex/schema.ts` with `defineSchema` / `defineTable`.
45- System Fields: `_id` (`v.id(tableName)`) and `_creationTime` (`v.number()`) are added automatically.
46- You MUST use `v.*` validators for every field; SHOULD avoid `v.any()` unless necessary.
47- Index naming: include all fields in the name, e.g., `"by_field1_and_field2"`.
48</rules>
49- Index rules:
50 - You MUST use `.index(name, [fields...])`.
51 - Field order matters; range expressions MUST follow index order.
52 - Limits: 16 fields per index, 32 indexes per table.
53
54### Function Rules
55- You MUST use new function syntax with `args`, `returns`, and `handler`.
56- You MUST always validate `args` and `returns` (HTTP actions excluded).
57- Use `query` for reads, `mutation` for writes, and `action` for external/long-running.
58- Actions MUST NOT access `ctx.db`; You MUST use `ctx.runQuery` / `ctx.runMutation`.
59- Circular Dependencies: When calling a function in the same file via `ctx.run*`, You MUST add explicit return type annotations to the receiver variable.
60
61### Database Operations
62- You MUST provide the explicit table name as the first argument to `ctx.db.get`, `ctx.db.patch`, `ctx.db.replace`, and `ctx.db.delete`.
63- Replacement: Use `ctx.db.replace` for full document replacement (throws if missing).
64- Patching: Use `ctx.db.patch` for shallow merge updates (throws if missing).
65- Deletion: Convex queries do NOT support `.delete()`. You MUST `.collect()` results and iterate to call `ctx.db.delete(id)`.
66- Unique: Use `.unique()` for single document results; it MUST throw if multiple documents match.
67- You MUST NOT use `filter` in production queries; use indexes and `.withIndex`.
68
69### TypeScript Best Practices
70- You MUST use `as const` for string literals in discriminated unions.
71- You MUST define arrays as `const array: Array<T> = [...]` and records as `const record: Record<K, V> = {...}`.
72- You MUST prefer `Id<"table">` over `string` for all document identifiers.
73
74### Query Performance
75- You SHOULD prefer `.withIndex` over `.filter` on large tables.
76- If using `.withIndex` without a range, You MUST pair it with `take`, `first`, `unique`, or `paginate`.
77- Search limits: `collect()` throws if >1024 docs; You SHOULD use `take(n)`, `paginate()`, or `for await` iteration for large sets.
78- Async iteration: Use `for await (const row of query)` instead of `.collect()` for streaming large result sets.
79
80### Pagination
81- You MUST use `paginationOptsValidator` in args.
82- `.paginate()` returns `{ page, isDone, continueCursor }`.
83- Pages are reactive; size MAY change.
84- You SHOULD avoid strict `returns` validators for the full `.paginate()` result object; validate `page` or use `v.any()`.
85
86### Client Patterns
87- You MUST use `api.*` references from `convex/_generated/api`.
88- React hooks: `useQuery`, `useMutation`, `useAction`, `usePaginatedQuery`.
89- You MUST NOT call mutations or actions during render.
90
91### Safety
92- You MUST enforce auth per function; check identity via `ctx.auth` helpers.
93- You MUST NOT expose sensitive logic in public functions; MUST use internal ones.
94
95</rules>