Convex Real-time Backend Specialist
Convex is a real-time reactive backend platform with TypeScript-first design, automatic caching, and optimistic updates.
Quick Reference
When to Use Convex
Use Convex for real-time collaborative applications including docs, whiteboards, and chat. Choose Convex for apps requiring instant UI updates without manual refetching. Select Convex for TypeScript-first projects needing end-to-end type safety. Use Convex for applications with complex optimistic update requirements.
Core Concepts
Server Functions include queries for read operations, mutations for write operations, and actions for external API calls.
Reactive Queries automatically re-execute when underlying data changes.
Optimistic Updates provide instant UI updates before server confirmation.
Automatic Caching provides built-in query result caching with intelligent invalidation.
Quick Start
Initialize a new Convex project using npm create convex@latest. Start the development server with npx convex dev.
Context7 Library
Use mcp__context7__resolve-library-id with "convex" to get the library ID, then use mcp__context7__get-library-docs for latest documentation.
Module Index
This skill is organized into specialized modules for detailed implementation guidance:
Reactive Queries Module
Location: modules/reactive-queries.md
Covers real-time reactive query patterns including basic query structure, index-based queries, search indexes, pagination patterns, React integration with useQuery hooks, and optimistic updates.
Server Functions Module
Location: modules/server-functions.md
Covers mutations for write operations, actions for external API integration, internal functions for server-to-server calls, scheduled functions using crons, and HTTP endpoints for webhooks.
Authentication Integration Module
Location: modules/auth-integration.md
Covers Clerk integration, Auth0 integration, server-side authentication patterns, authorization and role-based access control, and session management.
File Storage Module
Location: modules/file-storage.md
Covers file upload workflows, storage URL generation, client-side upload with progress, file display components, and file management operations.
Implementation Guide
Project Structure
A Convex project contains a convex directory with _generated subdirectory for auto-generated types and API, schema.ts for database schema definition, a functions subdirectory for server functions organized by domain, optional http.ts for HTTP endpoints, and optional crons.ts for scheduled jobs. The src directory contains ConvexProvider.tsx for client setup.
Schema Definition
The schema.ts file imports defineSchema and defineTable from convex/server and v from convex/values. The default export uses defineSchema to define tables. Each table is defined with defineTable specifying field types such as v.string(), v.boolean(), and v.number(). Tables can have indexes defined using the index method with index name and field array. Search indexes use the searchIndex method specifying searchField and filterFields.
Validators
The v module from convex/values provides primitive validators including v.string(), v.number(), v.boolean(), v.null(), v.int64(), and v.bytes().
Complex types include v.array() for arrays of a type, v.object() for objects with specified fields, v.union() for union types with v.literal() options, and v.optional() for optional fields.
Reference validators include v.id() for references to table documents.
React Client Setup
The ConvexProvider component imports ConvexProvider and ConvexReactClient from convex/react, ConvexProviderWithClerk from convex/react-clerk, and useAuth from @clerk/clerk-react. Create a ConvexReactClient instance with the VITE_CONVEX_URL environment variable. The Providers component wraps children with ConvexProviderWithClerk passing the client and useAuth hook.
React Hooks Usage
Import useQuery and useMutation from convex/react and api from the generated API module. In a component, call useQuery with the query function and parameters to get reactive data. Call useMutation to get a mutation function. Handle the undefined state during loading. Render the data and use the mutation function in event handlers.
Best Practices
Query Optimization:
- Use indexes for all filtered queries
- Prefer paginated queries for large datasets
- Use search indexes for full-text search
- Leverage automatic caching
Mutation Design:
- Keep mutations focused and atomic
- Use internal mutations for multi-step operations
- Validate all inputs with the v module
- Always check authorization
Error Handling:
- Use ConvexError for structured errors
- Check for undefined during loading states
- Handle optimistic update rollbacks
Works Well With
- moai-platform-supabase for alternative PostgreSQL-based backend
- moai-lang-typescript for TypeScript patterns and best practices
- moai-domain-frontend for React integration patterns
- moai-platform-clerk for Clerk authentication patterns
- moai-platform-auth0 for Auth0 authentication patterns
Resources
- Official Documentation at docs.convex.dev
- Context7 Library at /get-convex/convex
- GitHub at github.com/get-convex/convex
Status: Production Ready Version: 2.1.0 Last Updated: 2026-01-11 Platform: Convex Real-time Backend