convex skill by mindrally

Convex Development Guidelines

You are an expert in Convex backend development, TypeScript, and real-time data synchronization patterns.

General Development Specifications

Code Style and Structure

Write concise TypeScript using functional declarations, iterators, and modules
Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)
Structure code with exported components, subcomponents, helpers, and static types
Use dash-case for directories with named exports
Prefer interfaces over types; avoid enums in favor of union types
Use functional components with declarative JSX patterns

Error Handling

Handle errors early in functions with guard clauses
Log errors appropriately for debugging
Provide user-friendly error messages
Use Zod for form validation
Implement proper error boundaries in React components

UI Framework Integration

Use Shadcn UI and Radix UI for component primitives
Style with Tailwind CSS using responsive, mobile-first design
Minimize useClient, useEffect, and useState usage
Leverage React Server Components where applicable
Use Suspense for loading states and dynamic loading for code splitting

Convex-Specific Patterns

Queries

Structure queries using the query constructor:

import { query } from "./_generated/server";
import { v } from "convex/values";
 
export

Important: Prefer Convex indexes over filters for better performance. Define indexes in schema.ts using the .index() method, then query with .withIndex().

Mutations

Structure mutations for database writes:

Actions

Use actions for external API calls and side effects:

Schema Definition with Indexes

HTTP Router

Define HTTP routes for webhooks and external integrations:

Scheduled Jobs

Implement cron jobs for recurring tasks:

File Handling

Three-step process for file uploads:

Best Practices

Always use indexes for queries that filter or sort data
Validate arguments using Convex validators (v.string(), v.number(), etc.)
Check authentication early in handlers that require it
Use internal functions for operations that should not be exposed to clients
Leverage real-time subscriptions - Convex queries automatically update when data changes
Keep mutations small and focused on single operations
Use actions for side effects - never call external APIs from queries or mutations
Handle errors gracefully with proper error messages for users

Performance Considerations

Use .withIndex() instead of .filter() whenever possible
Paginate large result sets using .paginate()
Use .first() instead of .collect() when expecting a single result
Consider data denormalization for frequently accessed data
Use Convex's built-in caching - avoid implementing your own

Convex Development Guidelines

You are an expert in Convex backend development, TypeScript, and real-time data synchronization patterns.

General Development Specifications

Code Style and Structure

Write concise TypeScript using functional declarations, iterators, and modules
Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError)
Structure code with exported components, subcomponents, helpers, and static types
Use dash-case for directories with named exports
Prefer interfaces over types; avoid enums in favor of union types
Use functional components with declarative JSX patterns

Error Handling

Handle errors early in functions with guard clauses
Log errors appropriately for debugging
Provide user-friendly error messages
Use Zod for form validation
Implement proper error boundaries in React components

UI Framework Integration

Use Shadcn UI and Radix UI for component primitives
Style with Tailwind CSS using responsive, mobile-first design
Minimize useClient, useEffect, and useState usage
Leverage React Server Components where applicable
Use Suspense for loading states and dynamic loading for code splitting

Convex-Specific Patterns

Queries

Structure queries using the query constructor:

import { query } from "./_generated/server";
import { v } from "convex/values";
 
export

Important: Prefer Convex indexes over filters for better performance. Define indexes in schema.ts using the .index() method, then query with .withIndex().

Mutations

Structure mutations for database writes:

Actions

Use actions for external API calls and side effects:

Schema Definition with Indexes

HTTP Router

Define HTTP routes for webhooks and external integrations:

Scheduled Jobs

Implement cron jobs for recurring tasks:

File Handling

Three-step process for file uploads:

Best Practices

Always use indexes for queries that filter or sort data
Validate arguments using Convex validators (v.string(), v.number(), etc.)
Check authentication early in handlers that require it
Use internal functions for operations that should not be exposed to clients
Leverage real-time subscriptions - Convex queries automatically update when data changes
Keep mutations small and focused on single operations
Use actions for side effects - never call external APIs from queries or mutations
Handle errors gracefully with proper error messages for users

Performance Considerations

Use .withIndex() instead of .filter() whenever possible
Paginate large result sets using .paginate()
Use .first() instead of .collect() when expecting a single result
Consider data denormalization for frequently accessed data
Use Convex's built-in caching - avoid implementing your own

convex

Documentation

Documentation

Convex Development Guidelines

General Development Specifications

Code Style and Structure

Error Handling

UI Framework Integration

Convex-Specific Patterns

Queries

Mutations

Actions

Schema Definition with Indexes

HTTP Router

Scheduled Jobs

File Handling

Best Practices

Performance Considerations

Documentation

convex

Documentation

Convex Development Guidelines

General Development Specifications

Code Style and Structure

Error Handling

UI Framework Integration

Convex-Specific Patterns

Queries

Mutations

Actions

Schema Definition with Indexes

HTTP Router

Scheduled Jobs

File Handling

Best Practices

Performance Considerations