Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/get-convex/better-auth/llms.txt

Use this file to discover all available pages before exploring further.

Convex + Better Auth is a Convex Component that provides an integration layer for using Better Auth with Convex. Better Auth handles authentication logic — sessions, accounts, OAuth flows, two-factor auth, and more. The Convex component provides the database adapter, HTTP routing, and JWT/JWKS management that makes Better Auth work seamlessly inside a Convex backend.

​
Features

Email & password

Built-in support for email and password authentication with session and account management.

Social sign-on

Allow users to sign in with GitHub, Google, Discord, Twitter, and many more OAuth providers.

Two-factor auth

Secure user accounts with TOTP-based two-factor authentication with a few lines of code.

Transactional triggers

Run Convex mutations in the same transaction as auth events — onCreate, onUpdate, onDelete.

Framework support

Works with React (Vite SPA), Next.js, TanStack Start, SvelteKit, and Expo (React Native).

Full schema control

Use Local Install to own your auth schema and access all Better Auth plugins.

​
How it works

Better Auth is a framework-agnostic authentication library. Normally it needs a server-side runtime and a database. This component provides both within your Convex deployment:
  • Database adapter — translates Better Auth’s data model into Convex documents, so all auth data lives in your Convex database.
  • HTTP routing — mounts Better Auth’s /api/auth/* route handlers on your Convex HTTP router, so auth endpoints are served from your Convex deployment’s .convex.site URL.
  • JWT/JWKS management — issues signed JWTs for authenticated Convex queries and mutations, and exposes a JWKS endpoint so Convex can verify those tokens.
Your client uses Better Auth’s standard client library to sign in, sign up, and manage sessions. Convex uses the resulting JWT to authenticate queries and mutations just like any other Convex auth provider.

​
Prerequisites

Before installing Convex + Better Auth, you need:
  • An existing Convex project. Run npm create convex@latest if you don’t have one.
  • Convex 1.25.0 or later (convex package).
  • Better Auth 1.5.x — install the pinned version better-auth@1.5.3 --save-exact.
This component enforces the minimum Convex version at runtime. If you import @convex-dev/better-auth with an older version of Convex installed, it will throw an error immediately.

​
Framework guides

Installation steps differ slightly between frameworks. Choose yours to get started:

React (Vite SPA)

Client-side SPA using Vite and React

Next.js

Full-stack React with SSR and server components

TanStack Start

Full-stack React with TanStack Router

SvelteKit

Full-stack Svelte with SvelteKit

Expo (React Native)

Mobile apps with Expo and React Native
If you want a guided walkthrough that covers the steps common to every framework, see the Quickstart.

Build docs developers (and LLMs) love

Get started for freeTalk to us