Better Convex

Key Features

Tech Stack

Getting Started

Prerequisites

Setup Instructions

git clone <your-repo-url>
cd better-convex
bun install

cp .env.example .env.local

cp convex/.env.example convex/.env

# Required environment variables
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
RESEND_API_KEY=your_resend_api_key

# This will start both Next.js and Convex
bun dev

bun sync

Database Management

bun init # Populate with sample data
bun reset # Reset all tables
bun studio # Open Convex dashboard

Custom Convex Functions

Backend Functions (convex/functions.ts)

// Public query - auth optional
export const example = createPublicQuery()({
 args: { id: zid("items") }, // Always use zid() for IDs
 returns: z.object({ name: z.string() }).nullable(),
 handler: async (ctx, args) => {
 return await ctx.table("items").get(args.id);
 },
});
// Protected mutation with rate limiting
export const createItem = createAuthMutation({
 rateLimit: "item/create", // Auto tier limits
 role: "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 methods
 return await ctx.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 wrappers
const { data, isPending } = usePublicQuery(api.items.list, {}); // ALWAYS pass {} for no args
const { data } = useAuthQuery(api.user.getProfile, {}); // Skips if not auth
// Mutations with toast integration
const updateSettings = useAuthMutation(api.user.updateSettings);
toast.promise(updateSettings.mutateAsync({ name: "New" }), {
 loading: "Updating...",
 success: "Updated!",
 error: (e) => e.data?.message ?? "Failed",
});
// Paginated queries
const { data, hasNextPage, fetchNextPage } = usePublicPaginatedQuery(
 api.messages.list,
 { author: "alice" },
 { initialNumItems: 10 }
);

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

// Auth helpers for RSC
const token = await getSessionToken(); // Returns string | null
const user = await getSessionUser(); // Returns SessionUser & { token } | null
const isAuthenticated = await isAuth();
// Fetch with auth
const data = await fetchAuthQuery(api.user.getData, { id: userId });
const data = await fetchAuthQueryOrThrow(api.user.getData, { id: userId });

Schema & Database

Core Schema (Convex Ents)

// convex/schema.ts - Application data with relationships
const schema = 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 .claude/rules/convex.mdc

Authentication Context

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

Rate Limiting

export const rateLimiter = new RateLimiter(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/*.ts
args: {
 email: z.string().email(),
 id: zid('user') // Always use zid() for IDs
}

Development Commands

bun dev # Start dev servers
bun typecheck # Run TypeScript checks
bun lint # Check code with Ultracite/Biome
bun lint:fix # Fix linting and formatting issues
bun check # Run all checks (lint, ESLint, TypeScript)
bun seed # Seed database
bun reset # Reset database
bun 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.ts
src/lib/convex/
├── hooks/ # React hooks
├── server.ts # RSC helpers
├── auth-client.ts # Client auth setup
└── components/ # Auth components

Claude Agents & Cursor Rules

Cursor Rules (.claude/rules/)

Core Convex Rules

Frontend Rules

Start from Scratch

Backend Files to Delete (convex/)

# Function files
rm convex/todos.ts
rm convex/todoInternal.ts
rm convex/todoComments.ts
rm convex/projects.ts
rm convex/tags.ts
rm convex/seed.ts

Authentication Implementation

Admin Setup

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

Initialization (convex/init.ts)

Seeding (convex/seed.ts)

Reset (convex/reset.ts)

Frontend Files to Delete (src/)

# Page routes
rm -rf src/app/projects/
rm -rf src/app/tags/
# Components
rm -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 fields
 name: 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)

export default async function HomePage() {
 return (
 <div className="container mx-auto px-4 py-6">
 <h1 className="mb-4 text-3xl font-bold">Welcome</h1>
 <p>Your authenticated app starts here.</p>
 </div>
 );
}

Clean Generated Files

# Regenerate Convex types
bun dev

Resources