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.

This guide covers the universal setup steps that apply to every framework. After completing them, follow your framework-specific guide to finish the remaining configuration.
You need an existing Convex project before starting. Run npm create convex@latest if you don’t have one, then come back here.
1

Start the Convex dev server

Keep npx convex dev running throughout this setup. It initializes your deployment if it doesn’t exist yet, and keeps generated types current as you add files.
npx convex dev
2

Install packages

Install the component, ensure you have the latest version of Convex, and install a pinned version of Better Auth.
npm install convex@latest @convex-dev/better-auth
npm install better-auth@1.5.3 --save-exact
This component requires Convex 1.25.0 or later and is tested against Better Auth 1.5.x. Install better-auth@1.5.3 with an exact pin to avoid unexpected breaking changes from minor releases.
3

Register the component

Register the Better Auth component in your Convex project configuration.
convex/convex.config.ts
import { defineApp } from "convex/server";
import betterAuth from "@convex-dev/better-auth/convex.config";

const app = defineApp();
app.use(betterAuth);

export default app;
4

Add Convex auth config

Add a convex/auth.config.ts file to configure Better Auth as a Convex authentication provider. This is what tells Convex to trust JWTs issued by the component.
convex/auth.config.ts
import { getAuthConfigProvider } from "@convex-dev/better-auth/auth-config";
import type { AuthConfig } from "convex/server";

export default {
  providers: [getAuthConfigProvider()],
} satisfies AuthConfig;
5

Set environment variables

Generate a secret used for encryption and hashing, and set your site URL on your Convex deployment.
npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
npx convex env set SITE_URL http://localhost:3000
SITE_URL should be http://localhost:5173 for React (Vite) apps. Update it to your production URL before deploying.
6

Create a Better Auth instance

Create the Better Auth instance in convex/auth.ts. This example uses the React/Vite setup with the crossDomain plugin, which is required for client-side SPA frameworks.
convex/auth.ts
import { createClient, type GenericCtx } from "@convex-dev/better-auth";
import { convex, crossDomain } from "@convex-dev/better-auth/plugins";
import { components } from "./_generated/api";
import { DataModel } from "./_generated/dataModel";
import { query } from "./_generated/server";
import { betterAuth, type BetterAuthOptions } from "better-auth/minimal";
import authConfig from "./auth.config";

const siteUrl = process.env.SITE_URL!;

// The component client has methods needed for integrating Convex with Better Auth,
// as well as helper methods for general use.
export const authComponent = createClient<DataModel>(components.betterAuth);

export const createAuth = (ctx: GenericCtx<DataModel>) => {
  return betterAuth({
    trustedOrigins: [siteUrl],
    database: authComponent.adapter(ctx),
    // Configure simple, non-verified email/password to get started
    emailAndPassword: {
      enabled: true,
      requireEmailVerification: false,
    },
    plugins: [
      // The cross domain plugin is required for client-side frameworks
      crossDomain({ siteUrl }),
      // The Convex plugin is required for Convex compatibility
      convex({ authConfig }),
    ],
  });
};

// Example function for getting the current user
export const getCurrentUser = query({
  args: {},
  handler: async (ctx) => {
    return authComponent.getAuthUser(ctx);
  },
});
Full-stack frameworks like Next.js do not need the crossDomain plugin. See the Next.js guide for the server-side variant.
7

Register HTTP routes

Mount the Better Auth route handlers on your Convex HTTP router. This exposes the /api/auth/* endpoints from your Convex deployment’s .convex.site URL.
convex/http.ts
import { httpRouter } from "convex/server";
import { authComponent, createAuth } from "./auth";

const http = httpRouter();

// CORS handling is required for client-side frameworks
authComponent.registerRoutes(http, createAuth, { cors: true });

export default http;
8

Create an auth client

Create a Better Auth client instance for your frontend. This is used to call sign-in, sign-up, and session management methods from your UI code.
src/lib/auth-client.ts
import { createAuthClient } from "better-auth/react";
import {
  convexClient,
  crossDomainClient,
} from "@convex-dev/better-auth/client/plugins";

export const authClient = createAuthClient({
  baseURL: import.meta.env.VITE_CONVEX_SITE_URL,
  plugins: [convexClient(), crossDomainClient()],
});
9

Wrap your app with ConvexBetterAuthProvider

Replace the standard ConvexProvider with ConvexBetterAuthProvider. It handles token management and keeps your Convex client authenticated.
src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./index.css";
import { ConvexReactClient } from "convex/react";
import { ConvexBetterAuthProvider } from "@convex-dev/better-auth/react";
import { authClient } from "@/lib/auth-client";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string, {
  // Optionally pause queries until the user is authenticated
  expectAuth: true,
});

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <ConvexBetterAuthProvider client={convex} authClient={authClient}>
      <App />
    </ConvexBetterAuthProvider>
  </React.StrictMode>
);

​
Next steps

The steps above are the common foundation. Each framework has additional configuration — environment variable names, provider setup, and SSR utilities differ. Follow your framework guide to complete the setup:

React (Vite SPA)

Full install guide for React SPAs with Vite

Next.js

Full install guide with SSR, server components, and route handlers

TanStack Start

Full install guide for TanStack Start

SvelteKit

Full install guide for SvelteKit

Expo (React Native)

Full install guide for Expo
Once installed, see Basic Usage for sign-in, sign-up, and session management patterns, or browse Supported Plugins to add 2FA, magic links, OTP, and more.

Build docs developers (and LLMs) love

Get started for freeTalk to us