Convex Helpers Guide Use convex-helpers to add common patterns and utilities to your Convex backend without reinventing the wheel. What is convex-helpers? convex-helpers is the official collection of utilities that complement Convex. It provides battle-tested patterns for common backend needs. Installation: npm install convex-helpers Available Helpers 1. Relationship Helpers Traverse relationships between tables in a readable, type-safe way. Use when: Loading related data across tables Following foreign key relationships Building nested data structures Example: import { getOneFrom , getManyFrom } from "convex-helpers/server/relationships" ; export const getTaskWithUser = query ( { args : { taskId : v . id ( "tasks" ) } , handler : async ( ctx , args ) => { const task = await ctx . db . get ( args . taskId ) ; if ( ! task ) return null ; // Get related user const user = await getOneFrom ( ctx . db , "users" , "by_id" , task . userId , "_id" ) ; // Get related comments const comments = await getManyFrom ( ctx . db , "comments" , "by_task" , task . _id , "taskId" ) ; return { ... task , user , comments } ; } , } ) ; Key Functions: getOneFrom - Get single related document getManyFrom - Get multiple related documents getManyVia - Get many-to-many relationships through junction table 2. Custom Functions (Data Protection) - MOST IMPORTANT This is Convex's alternative to Row Level Security (RLS). Instead of database-level policies, use custom function wrappers to automatically add auth and access control to all queries and mutations. Create wrapped versions of query/mutation/action with custom behavior. Use when: Data protection and access control (PRIMARY USE CASE) Want to add auth logic to all functions Multi-tenant applications Role-based access control (RBAC) Need to inject common data into ctx Building internal-only functions Adding logging/monitoring to all functions Why this instead of RLS: TypeScript, not SQL policies Full type safety Easy to test and debug More flexible than database policies Works across your entire backend Example: Custom Query with Auto-Auth // convex/lib/customFunctions.ts import { customQuery } from "convex-helpers/server/customFunctions" ; import { query } from "../_generated/server" ; export const authenticatedQuery = customQuery ( query , { args : { } , // No additional args required input : async ( ctx , args ) => { const identity = await ctx . auth . getUserIdentity ( ) ; if ( ! identity ) { throw new Error ( "Not authenticated" ) ; } const user = await ctx . db . query ( "users" ) . withIndex ( "by_token" , q => q . eq ( "tokenIdentifier" , identity . tokenIdentifier ) ) . unique ( ) ; if ( ! user ) throw new Error ( "User not found" ) ; // Add user to context return { ctx : { ... ctx , user } , args } ; } , } ) ; // Usage in your functions export const getMyTasks = authenticatedQuery ( { handler : async ( ctx ) => { // ctx.user is automatically available! return await ctx . db . query ( "tasks" ) . withIndex ( "by_user" , q => q . eq ( "userId" , ctx . user . _id ) ) . collect ( ) ; } , } ) ; Example: Multi-Tenant Data Protection import { customQuery } from "convex-helpers/server/customFunctions" ; import { query } from "../_generated/server" ; // Organization-scoped query - automatic access control export const orgQuery = customQuery ( query , { args : { orgId : v . id ( "organizations" ) } , input : async ( ctx , args ) => { const user = await getCurrentUser ( ctx ) ; // Verify user is a member of this organization const member = await ctx . db . query ( "organizationMembers" ) . withIndex ( "by_org_and_user" , q => q . eq ( "orgId" , args . orgId ) . eq ( "userId" , user . _id ) ) . unique ( ) ; if ( ! member ) { throw new Error ( "Not authorized for this organization" ) ; } // Inject org context return { ctx : { ... ctx , user , orgId : args . orgId , role : member . role } , args } ; } , } ) ; // Usage - data automatically scoped to organization export const getOrgProjects = orgQuery ( { args : { orgId : v . id ( "organizations" ) } , handler : async ( ctx ) => { // ctx.user and ctx.orgId automatically available and verified! return await ctx . db . query ( "projects" ) . withIndex ( "by_org" , q => q . eq ( "orgId" , ctx . orgId ) ) . collect ( ) ; } , } ) ; Example: Role-Based Access Control import { customMutation } from "convex-helpers/server/customFunctions" ; import { mutation } from "../_generated/server" ; export const adminMutation = customMutation ( mutation , { args : { } , input : async ( ctx , args ) => { const user = await getCurrentUser ( ctx ) ; if ( user . role !== "admin" ) { throw new Error ( "Admin access required" ) ; } return { ctx : { ... ctx , user } , args } ; } , } ) ; // Usage - only admins can call this export const deleteUser = adminMutation ( { args : { userId : v . id ( "users" ) } , handler : async ( ctx , args ) => { // Only admins reach this code await ctx . db . delete ( args . userId ) ; } , } ) ; 3. Filter Helper Apply complex TypeScript filters to database queries. Use when: Need to filter by computed values Filtering logic is too complex for indexes Working with small result sets Example: import { filter } from "convex-helpers/server/filter" ; export const getActiveTasks = query ( { handler : async ( ctx ) => { const now = Date . now ( ) ; const threeDaysAgo = now - 3 * 24 * 60 * 60 * 1000 ; return await filter ( ctx . db . query ( "tasks" ) , ( task ) => ! task . completed && task . createdAt
threeDaysAgo && task . priority === "high" ) . collect ( ) ; } , } ) ; Note: Still prefer indexes when possible! Use filter for complex logic that can't be indexed. 4. Sessions Track users across requests even when not logged in. Use when: Need to track anonymous users Building shopping cart for guests Tracking user behavior before signup A/B testing without auth Setup: // convex/sessions.ts import { SessionIdArg } from "convex-helpers/server/sessions" ; import { query } from "./_generated/server" ; export const trackView = query ( { args : { ... SessionIdArg , // Adds sessionId: v.string() pageUrl : v . string ( ) , } , handler : async ( ctx , args ) => { await ctx . db . insert ( "pageViews" , { sessionId : args . sessionId , pageUrl : args . pageUrl , timestamp : Date . now ( ) , } ) ; } , } ) ; Client (React): import { useSessionId } from "convex-helpers/react/sessions" ; import { useQuery } from "convex/react" ; import { api } from "../convex/_generated/api" ; function MyComponent ( ) { const sessionId = useSessionId ( ) ; // Automatically includes sessionId in all requests useQuery ( api . sessions . trackView , { sessionId , pageUrl : window . location . href , } ) ; } 5. Zod Validation Use Zod schemas instead of Convex validators. Use when: Already using Zod in your project Want more complex validation logic Need custom error messages Example: import { zCustomQuery } from "convex-helpers/server/zod" ; import { z } from "zod" ; import { query } from "./_generated/server" ; const argsSchema = z . object ( { email : z . string ( ) . email ( ) , age : z . number ( ) . min ( 18 ) . max ( 120 ) , } ) ; export const createUser = zCustomQuery ( query , { args : argsSchema , handler : async ( ctx , args ) => { // args is typed from Zod schema return await ctx . db . insert ( "users" , args ) ; } , } ) ; 6. Alternative: Row-Level Security Helper Note: Convex recommends using custom functions (see #2 above) as the primary data protection pattern. This RLS helper is an alternative approach that mimics traditional RLS. However, custom functions are usually better because: Type-safe at compile time (RLS is runtime) More explicit (easy to see what auth is applied) Better error messages Easier to test 7. Migrations Run data migrations safely. Use when: Backfilling new fields Transforming existing data Moving between schema versions Example: import { makeMigration } from "convex-helpers/server/migrations" ; export const addDefaultPriority = makeMigration ( { table : "tasks" , migrateOne : async ( ctx , doc ) => { if ( doc . priority === undefined ) { await ctx . db . patch ( doc . _id , { priority : "medium" } ) ; } } , } ) ; // Run: npx convex run migrations:addDefaultPriority 8. Triggers Execute code automatically when data changes. Use when: Sending notifications on data changes Updating related records Logging changes Maintaining computed fields Example: import { Triggers } from "convex-helpers/server/triggers" ; const triggers = new Triggers ( ) ; triggers . register ( "tasks" , "insert" , async ( ctx , task ) => { // Send notification when task is created await ctx . db . insert ( "notifications" , { userId : task . userId , type : "task_created" , taskId : task . _id , } ) ; } ) ; Common Patterns Pattern 1: Authenticated Queries with User Context import { customQuery } from "convex-helpers/server/customFunctions" ; export const authedQuery = customQuery ( query , { args : { } , input : async ( ctx , args ) => { const user = await getCurrentUser ( ctx ) ; return { ctx : { ... ctx , user } , args } ; } , } ) ; // Now all queries automatically have user in context export const getMyData = authedQuery ( { handler : async ( ctx ) => { // ctx.user is typed and available! return await ctx . db . query ( "data" ) . withIndex ( "by_user" , q => q . eq ( "userId" , ctx . user . _id ) ) . collect ( ) ; } , } ) ; Pattern 2: Loading Related Data import { getOneFrom , getManyFrom } from "convex-helpers/server/relationships" ; export const getPostWithDetails = query ( { args : { postId : v . id ( "posts" ) } , handler : async ( ctx , args ) => { const post = await ctx . db . get ( args . postId ) ; if ( ! post ) return null ; const author = await getOneFrom ( ctx . db , "users" , "by_id" , post . authorId , "_id" ) ; const comments = await getManyFrom ( ctx . db , "comments" , "by_post" , post . _id , "postId" ) ; const tagLinks = await getManyFrom ( ctx . db , "postTags" , "by_post" , post . _id , "postId" ) ; const tags = await Promise . all ( tagLinks . map ( link => getOneFrom ( ctx . db , "tags" , "by_id" , link . tagId , "_id" ) ) ) ; return { ... post , author , comments , tags } ; } , } ) ; Pattern 3: Batch Operations with Error Handling import { asyncMap } from "convex-helpers" ; export const batchUpdateTasks = mutation ( { args : { taskIds : v . array ( v . id ( "tasks" ) ) , status : v . string ( ) , } , handler : async ( ctx , args ) => { const results = await asyncMap ( args . taskIds , async ( taskId ) => { try { const task = await ctx . db . get ( taskId ) ; if ( task ) { await ctx . db . patch ( taskId , { status : args . status } ) ; return { success : true , taskId } ; } return { success : false , taskId , error : "Not found" } ; } catch ( error ) { return { success : false , taskId , error : error . message } ; } } ) ; return results ; } , } ) ; When to Use What Need Use Import From Load related data getOneFrom , getManyFrom convex-helpers/server/relationships Auth in all functions customQuery convex-helpers/server/customFunctions Complex filters filter convex-helpers/server/filter Anonymous users useSessionId convex-helpers/react/sessions Zod validation zCustomQuery convex-helpers/server/zod Data migrations makeMigration convex-helpers/server/migrations Triggers Triggers convex-helpers/server/triggers Checklist Installed convex-helpers: npm install convex-helpers Using relationship helpers for related data Created custom functions for common auth patterns Using sessions for anonymous tracking (if needed) Prefer indexes over filter when possible Check convex-helpers docs for new utilities