Convex Development Guide

Provide comprehensive Convex development guidance to avoid common mistakes and ensure code compiles on first try.

Priorities

1. Compile + typecheck on first try
2. Respect Convex's constraints (indexes, limits, auth, schedulers, file storage)
3. Avoid expensive / subtle bugs (wrong indexes, misuse of actions, broken hooks)

Mental Model

Convex is a hosted backend with:

• Database: documents + indexes + full-text search
• Functions: query, mutation, action, plus internal variants
• Realtime queries: useQuery on the client auto-subscribes
• File storage, Auth (via @convex-dev/auth), Scheduler (cron + runAfter)

Code layout:

• Backend: convex/*.ts files
• Client: React using convex/react (useQuery, useMutation)
• Generated API: convex/_generated/api exports api + internal

Quick Reference

Functions

• Import from ./_generated/server
• Use query({ args, handler }) syntax
• Always define args validators

Indexes (CRITICAL)

• Never use .filter() - use .withIndex() instead
• Never define by_creation_time index (it's built-in)
• Never include _creationTime in custom index fields

Actions

• Add "use node"; at top for Node modules
• Never use ctx.db - use ctx.runQuery/ctx.runMutation
• Only actions support dynamic imports

Scheduler

• Auth does NOT propagate - use internal functions
• Use function references (internal.file.fn), not the function itself

Migrations

• Install @convex-dev/migrations component
• Modify schema to allow old+new values → run migration → update schema to require new values
• Use migrations.define({ table, migrateOne }) to define
• Return object from migrateOne for auto-patch shorthand
• Run via CLI: npx convex run migrations:run '{fn: "migrations:myMigration"}'
• Use dryRun: true to validate before committing

React Hooks

• Never call hooks conditionally
• Use "skip" pattern: useQuery(api.foo, condition ? args : "skip")
• usePaginatedQuery returns { results, status, loadMore } for infinite scroll

Testing

• Use convex-test with Vitest
• Pass schema to convexTest() for validation
• Use t.withIdentity() for auth testing

Reference Files

Load these as needed based on the task:

Process

1. Check the quick reference above for common patterns
2. Load specific reference files based on the task
3. Verify against the checklist before finalizing code