Convex Backend Development Skill

CRITICAL: Activation Protocol

Before proceeding with ANY Convex-related implementation:

1. •EVALUATE: Is this question about Convex backend, database, functions, or data operations?
2. •ACTIVATE: If YES, you MUST use this skill for accurate Convex implementation patterns.
3. •COMMIT: State "ACTIVATING CONVEX SKILL" before proceeding.

When to Use This Skill

MANDATORY activation for:

• •Database queries and mutations
• •Schema definitions and validation
• •Query, mutation, and action functions
• •Real-time data subscriptions
• •Authentication setup (Auth.js, Clerk, custom)
• •File storage operations
• •Scheduled jobs and cron tasks
• •HTTP API endpoints
• •Full-text search implementation
• •AI agent integration
• •Convex Components
• •Deployment and environment configuration
• •Data import/export
• •Testing Convex functions
• •Performance optimization and indexes
• •Any question containing: Convex, query, mutation, action, ctx, db, schema, useQuery, useMutation

DO NOT use for:

• •Pure React component styling (use design-guidance skill)
• •Frontend routing unrelated to data fetching
• •General TypeScript questions without Convex context
• •UI/UX design patterns

Documentation Location

All Convex documentation is located in: .claude/skills/convex/docs

Key documentation areas:

• •Database: docs/database/ - Reading, writing, schemas, types, pagination
• •Functions: docs/functions.mdx - Queries, mutations, actions
• •Auth: docs/auth/ - Authentication patterns and providers
• •File Storage: docs/file-storage/ - Upload and manage files
• •Scheduling: docs/scheduling/ - Cron jobs and scheduled functions
• •HTTP API: docs/http-api/ - External HTTP endpoints
• •Search: docs/search/ - Full-text search implementation
• •AI/Agents: docs/agents.mdx, docs/ai.mdx - AI integration
• •Components: docs/components/ - Reusable Convex components
• •Production: docs/production/ - Deployment, hosting, integrations
• •Testing: docs/testing/ - Test patterns for Convex functions
• •CLI: docs/cli.md - Command-line interface

Core Convex Concepts

Functions (queries, mutations, actions)

• •Queries: Read-only, real-time reactive, cached
• •Mutations: Write operations, transactional, consistent
• •Actions: External integrations, non-transactional, async operations

Database Operations

• •Document-based NoSQL database
• •Strong consistency with OCC (Optimistic Concurrency Control)
• •Automatic indexes for queries
• •Schema validation with TypeScript types

Real-time Subscriptions

• •useQuery hook for reactive data
• •Automatic cache invalidation
• •Optimistic updates with useMutation

Core Principles

1. •Type Safety: Use generated types from schema with defineSchema
2. •Reactive Data: Prefer queries over actions for data that needs real-time updates
3. •Consistent Writes: Use mutations for all database writes
4. •Indexes: Define indexes for efficient query performance
5. •Schema Validation: Validate all data with v validators
6. •Error Handling: Use ConvexError for user-facing errors
7. •Security: Implement auth checks in every function that needs protection

Common Patterns

Query Pattern

export const listItems = query({
  args: { limit: v.optional(v.number()) },
  handler: async (ctx, args) => {
    return await ctx.db.query("items")
      .withIndex("by_creation_time")
      .order("desc")
      .take(args.limit ?? 10);
  },
});

Mutation Pattern

export const createItem = mutation({
  args: { name: v.string(), description: v.string() },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Unauthenticated");

    return await ctx.db.insert("items", {
      name: args.name,
      description: args.description,
      userId: identity.subject,
      createdAt: Date.now(),
    });
  },
});

Action Pattern

export const sendEmail = action({
  args: { to: v.string(), subject: v.string(), body: v.string() },
  handler: async (ctx, args) => {
    // Call external API
    await fetch("https://api.email-service.com/send", {
      method: "POST",
      body: JSON.stringify(args),
    });
  },
});

Workflow

1. •Evaluate Question: Determine if Convex-related
2. •Identify Topic: Database, auth, functions, file storage, etc.
3. •Search Documentation: Use Grep to find relevant docs in the topic area
4. •Read Specific Docs: Read the relevant documentation files
5. •Apply Patterns: Follow established Convex patterns and best practices
6. •Generate Code: Provide type-safe, validated, production-ready code

Progressive Documentation Reading

Only read documentation files when necessary:

• •Level 1: Answer from common patterns if straightforward
• •Level 2: Grep for relevant topics in docs folder
• •Level 3: Read specific documentation files for the topic
• •Level 4: Read related advanced topics or edge cases

Never read entire documentation at once. Use targeted searches.

Output Format

Generate code that:

• •Uses Convex function builders (query, mutation, action)
• •Includes argument validation with v validators
• •Implements proper authentication checks
• •Uses TypeScript with generated types
• •Follows Convex naming conventions
• •Includes error handling with ConvexError
• •Uses proper indexes for queries
• •Follows best practices from documentation

Key File Locations in User Projects

Standard Convex project structure:

• •convex/schema.ts - Database schema definitions
• •convex/*.ts - Function definitions (queries, mutations, actions)
• •convex/_generated/api.d.ts - Generated API types
• •convex.json - Configuration file
• •.env.local - Environment variables (CONVEX_URL, etc.)

Common Tasks

Schema Definition

Check docs/database/schemas.mdx for schema patterns and validation.

Authentication Setup

Check docs/auth/ for authentication provider integration.

File Uploads

Check docs/file-storage/ for file storage patterns.

Real-time Search

Check docs/search/ for full-text search implementation.

Scheduled Jobs

Check docs/scheduling/ for cron and scheduled function patterns.

HTTP Endpoints

Check docs/http-api/ for external API endpoint creation.

Testing

Check docs/testing/ for test patterns and setup.

Important Notes

• •Convex uses its own function definition syntax (not raw async functions)
• •Always validate arguments with v validators
• •Use ctx.db for database operations, not direct database access
• •Use ctx.auth for authentication, not manual token parsing
• •Queries are cached and reactive, mutations are not
• •Actions can call third-party APIs, queries and mutations cannot
• •Use indexes for efficient queries (check query performance in dashboard)