Key Features

Tech Stack

Getting Started

Prerequisites

Setup Instructions

git clone<your-repo-url>cd better-convexpnpm install

cp .env.example .env.local

cp convex/.env.example convex/.env

# Required environment variablesGITHUB_CLIENT_ID=your_github_client_idGITHUB_CLIENT_SECRET=your_github_client_secretGOOGLE_CLIENT_ID=your_google_client_idGOOGLE_CLIENT_SECRET=your_google_client_secretRESEND_API_KEY=your_resend_api_key

# This will start both Next.js and Convexpnpm dev

pnpm sync

Database Management

pnpm init# Populate with sample datapnpm reset# Reset all tablespnpm studio# Open Convex dashboard

Custom Convex Functions

Backend Functions (convex/functions.ts)

// Public query - auth optionalexportconstexample=createPublicQuery()({args:{id:zid("items")},// Always use zid() for IDsreturns:z.object({name:z.string()}).nullable(),handler:async(ctx,args)=>{returnawaitctx.table("items").get(args.id);},});// Protected mutation with rate limitingexportconstcreateItem=createAuthMutation({rateLimit:"item/create",// Auto tier limitsrole:"admin",// Optional role check (lowercase)})({args:{name:z.string().min(1).max(100)},returns:zid("items"),handler:async(ctx,args)=>{// ctx.user is pre-loaded SessionUser with ent methodsreturnawaitctx.table("items").insert({name:args.name,userId:ctx.user._id,});},});

Client-Side Helpers

React Hooks (src/lib/convex/hooks)

// Never use useQuery directly - use these wrappersconst{ data, isPending}=usePublicQuery(api.items.list,{});// ALWAYS pass {} for no argsconst{ data}=useAuthQuery(api.user.getProfile,{});// Skips if not auth// Mutations with toast integrationconstupdateSettings=useAuthMutation(api.user.updateSettings);toast.promise(updateSettings.mutateAsync({name:"New"}),{loading:"Updating...",success:"Updated!",error:(e)=>e.data?.message??"Failed",});// Paginated queriesconst{ data, hasNextPage, fetchNextPage}=usePublicPaginatedQuery(api.messages.list,{author:"alice"},{initialNumItems:10});

Server Components (src/lib/convex/server.ts)

// Auth helpers for RSCconsttoken=awaitgetSessionToken();// Returns string | nullconstuser=awaitgetSessionUser();// Returns SessionUser & { token } | nullconstisAuthenticated=awaitisAuth();// Fetch with authconstdata=awaitfetchAuthQuery(api.user.getData,{id:userId});constdata=awaitfetchAuthQueryOrThrow(api.user.getData,{id:userId});

Schema & Database

Core Schema (Convex Ents)

// convex/schema.ts - Application data with relationshipsconstschema=defineEntSchema({user:defineEnt({name:v.optional(v.string()),bio:v.optional(v.string()),personalOrganizationId:v.string(),// Every user has a personal org}).field("email",v.string(),{unique:true}).edges("subscriptions",{ref:"userId"})// Polar subscriptions.edges("todos",{ref:true}).edges("ownedProjects",{to:"projects",ref:"ownerId"}),todos:defineEnt({title:v.string(),description:v.optional(v.string()),}).field("completed",v.boolean(),{index:true}).deletion("soft")// Soft delete support.edge("user").edge("project",{optional:true}).edges("tags")// Many-to-many.searchIndex("search_title_description",{searchField:"title",filterFields:["userId","completed"],}),});

Better Auth Schema

// convex/authSchema.ts - Auto-generated auth tables// Generated via: cd convex && npx @better-auth/cli generate -y --output authSchema.ts// Includes: user, session, account, organization, member, invitation

Key Patterns from.cursor/rules/convex.mdc

Authentication Context

handler:async(ctx,args)=>{// ❌ Don't refetch the userconstuser=awaitctx.table("user").get(ctx.user._id);// ✅ Use pre-loaded userawaitctx.user.patch({credits:ctx.user.credits-1});};

Rate Limiting

exportconstrateLimiter=newRateLimiter(components.rateLimiter,{'comment/create:free':{kind:'fixed window',period:MINUTE,rate:10},'comment/create:premium':{kind:'fixed window',period:MINUTE,rate:30},});// Auto-selects tier based on user plan (free/premium)createAuthMutation({rateLimit:'comment/create'})({...});

Validators

// Schema (v.) - in convex/schema.ts.field('email',v.string(),{unique:true})// Functions (z.) - in convex/*.tsargs:{email:z.string().email(),id:zid('user')// Always use zid() for IDs}

Development Commands

pnpm dev# Start dev serverspnpm typecheck# Run TypeScript checkspnpm lint# Check code with Ultracite/Biomepnpm lint:fix# Fix linting and formatting issuespnpm check# Run all checks (lint, ESLint, TypeScript)pnpm seed# Seed databasepnpm reset# Reset databasepnpm studio# Open Convex dashboard

Best Practices

File Structure

convex/├── functions.ts      # Custom function wrappers├── schema.ts         # Database schema├── auth.ts          # Better Auth setup├── todos.ts         # Example CRUD operations└── helpers/    └── rateLimiter.tssrc/lib/convex/├── hooks/           # React hooks├── server.ts        # RSC helpers├── auth-client.ts   # Client auth setup└── components/      # Auth components

Claude Agents & Cursor Rules

Cursor Rules (.cursor/rules/)

Core Convex Rules

Frontend Rules

Start from Scratch

Backend Files to Delete (convex/)

# Function filesrm convex/todos.tsrm convex/todoInternal.tsrm convex/todoComments.tsrm convex/projects.tsrm convex/tags.tsrm convex/seed.ts

Authentication Implementation

Admin Setup

# convex/.envADMIN="admin@example.com,another@example.com"

Initialization (convex/init.ts)

Seeding (convex/seed.ts)

Reset (convex/reset.ts)

Frontend Files to Delete (src/)

# Page routesrm -rf src/app/projects/rm -rf src/app/tags/# Componentsrm -rf src/components/todos/rm -rf src/components/projects/# Breadcrumb navigation (optional - uses todo examples)rm src/components/breadcrumb-nav.tsx

Schema Updates (convex/schema.ts)

user:defineEnt({// Keep profile fieldsname:v.optional(v.string()),bio:v.optional(v.string()),image:v.optional(v.string()),role:v.optional(v.string()),deletedAt:v.optional(v.number()),}).field("emailVerified",v.boolean(),{default:false}).field("email",v.string(),{unique:true});// Remove all todo/project related edges

Aggregates Updates (convex/aggregates.ts)

Config Updates (convex/convex.config.ts)

// Keep only:app.use(aggregate,{name:"aggregateUsers"});// Remove all todo/project/tag related aggregates

Triggers Updates (convex/triggers.ts)

Home Page Update (src/app/page.tsx)

exportdefaultasyncfunctionHomePage(){return(<divclassName="container mx-auto px-4 py-6"><h1className="mb-4 text-3xl font-bold">Welcome</h1><p>Your authenticated app starts here.</p></div>);}

Clean Generated Files

# Regenerate Convex typespnpm dev

Resources