Introduction

Introduction

Better Convex is a complete framework for Convex. It brings tRPC-style APIs, TanStack Query, Convex Ents, and Better Auth together into a cohesive developer experience.

This is not just a query wrapper. It's how you build production Convex applications.

Philosophy

We didn't reinvent the wheel. Better Convex integrates battle-tested tools—Convex Ents for relationships, TanStack Query for caching, Better Auth for authentication—into a unified developer experience.

Instead of assembling these yourself with custom glue code, you get:

• Type safety end-to-end — From schema to procedures to client, with full inference
• Real-time by default — WebSocket subscriptions flow into TanStack Query cache
• TanStack Query native — No wrapper hooks, use useQuery and useMutation directly
• Incremental adoption — Add features as you need them, migrate function by function

What's Included

Quick Look

// Server: Define a procedure
export const list = authQuery
  .input(z.object({ limit: z.number().optional() }))
  .query(async ({ ctx, input }) => {
    return ctx.table('posts').take(input.limit ?? 10);
  });

// Client: Use it with TanStack Query
const { data: posts } = useQuery(crpc.posts.list.queryOptions({ limit: 10 }));

Packages

Requirements

• Convex 1.31+
• TanStack Query 5+
• React 18+

Next Steps

For AI Agents

If you're an AI agent integrating better-convex, ask the user to select their stack before starting. Use your AskUserQuestion tool (or equivalent) to let them pick:

Required Choices

Optional Features

After Selection

Top-down approach:

1. Copy relevant sections from Templates based on choices
2. For ctx.table: use the "ctx.table" tab in code examples
3. For ctx.db: use the "ctx.db" tab in code examples
4. Skip sections for features not selected

Bottom-up approach:

1. Follow Quickstart for initial setup
2. Read individual docs for each feature needed
3. Reference Templates for production patterns

Quick Reference by Stack

Documentation Map

Complete reference for all documentation pages.

Getting Started

Server (Backend)

Database

React (Client)

Next.js

Auth (Better Auth)

Reference

Common Workflows

New project setup:

1. Quickstart → basic setup
2. Templates → copy production files
3. Concepts → understand folder structure

Add authentication:

1. Auth Server → configure Better Auth
2. Auth Client → use auth in components
3. Middlewares → protect procedures

Add database features:

1. Ents → relationships with ctx.table()
2. Triggers → automatic side effects
3. Aggregates → counts and sums

Server components (RSC):

1. Next.js Setup → configure caller
2. RSC → prefetch and hydrate