Convex Better Auth

https://labs.convex.dev/better-auth
Admin
Convex Better Auth is a Convex Component that provides an integration layer for using Better Auth...
Tokens:44,214
Snippets:385
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install packages for TanStack Start

Source: https://labs.convex.dev/better-auth/framework-guides/tanstack-start

Install the Convex Better Auth component, a pinned version of Better Auth, and the latest Convex. Requires Convex 1.25.0 or later.

```bash
npm install convex@latest @convex-dev/better-auth
npm install better-auth@~1.6.15
npm install @types/node --save-dev
```

--------------------------------

### Install convex and @mmailaender/convex-svelte with npm

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Install the Convex and SvelteKit integration packages. This is the npm command shown in the installation tab.

```bash
npm install convex @mmailaender/convex-svelte
```

--------------------------------

### Install migrations component

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-9/migrate-userid/userid-in-app-table

Install the @convex-dev/migrations package.

```bash
npm install @convex-dev/migrations
```

--------------------------------

### Install expo-secure-store

Source: https://labs.convex.dev/better-auth/framework-guides/expo

Install expo-secure-store for secure cookie storage.

```bash
npx expo install expo-secure-store
```

--------------------------------

### Install dependencies for migration

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-10

Install the required package versions for the migration. Pin better-auth to 1.4.9 exactly and use the ^0.10.0 range for the component.

```bash
npm install @convex-dev/better-auth@^0.10.0
npm install better-auth@1.4.9 --save-exact
```

--------------------------------

### Install Convex and Better Auth packages

Source: https://labs.convex.dev/better-auth/framework-guides/expo

Install the Convex and Better Auth packages. Requires Convex 1.25.0 or later.

```bash
npm install convex@latest @convex-dev/better-auth
npm install better-auth@~1.6.15 @better-auth/expo@~1.6.15
```

--------------------------------

### Install @convex-dev/better-auth@^0.11.0 and better-auth

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-11

Install the updated Better Auth component and the Better Auth package. Review breaking changes in Better Auth 1.5 before upgrading.

```bash
npm install @convex-dev/better-auth@^0.11.0
npm install better-auth
```

--------------------------------

### Install packages with npm

Source: https://labs.convex.dev/better-auth/framework-guides/react

Install the Convex component, a pinned version of Better Auth, and the latest Convex. Requires Convex 1.25.0 or later.

```bash
npm install convex@latest @convex-dev/better-auth
npm install better-auth@~1.6.15
```

--------------------------------

### adapter() - Get Convex database adapter

Source: https://labs.convex.dev/better-auth/api/component-client

Returns the Convex database adapter for use in Better Auth options. The example shows creating a client with createClient and passing the adapter to betterAuth.

```typescript
import { createClient } from "@convex-dev/better-auth";
import { components } from "./_generated/api";
import { type GenericCtx } from "./_generated/server";
import { DataModel } from "./_generated/dataModel";

export const authComponent = createClient<DataModel>(components.betterAuth);

export const createAuth = (ctx: GenericCtx<DataModel>) => {
  return betterAuth({
    database: authComponent.adapter(ctx),
  });
});
```

--------------------------------

### Install @convex-dev/better-auth@0.8 and better-auth@1.3.8

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-8

Install the updated Better Auth component and the matching Better Auth version. Use the npm package manager.

```bash
npm install @convex-dev/better-auth@0.8
npm install better-auth@1.3.8 --save-exact
```

--------------------------------

### Install Better Auth packages (npm)

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Install the Convex Better Auth component, the SvelteKit helper package, and a pinned version of Better Auth. Requires Convex 1.25.0 or later.

```bash
npm install @convex-dev/better-auth @mmailaender/convex-better-auth-svelte
npm install better-auth@~1.6.15
```

--------------------------------

### Update server utilities for Next.js and TanStack Start

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-10

Replace previous server utilities with the new ones. The Next.js version uses `convexBetterAuthNextJs` with `NEXT_PUBLIC_CONVEX_URL` and `NEXT_PUBLIC_CONVEX_SITE_URL`; the TanStack Start version uses `convexBetterAuthReactStart` with `VITE_CONVEX_URL` and `VITE_CONVEX_SITE_URL`. The new functions only accept a function reference and arguments; a third option with configuration such as a token is not accepted or required.

```typescript
import { createAuth } from "@/convex/auth"; 
import { getToken as getTokenNextjs } from "@convex-dev/better-auth/nextjs"; 
import { convexBetterAuthNextJs } from "@convex-dev/better-auth/nextjs"; 

export const getToken = () => {
  return getTokenNextjs(createAuth);
};

export const {
  handler,
  preloadAuthQuery,
  isAuthenticated,
  getToken,
  fetchAuthQuery,
  fetchAuthMutation,
  fetchAuthAction,
} = convexBetterAuthNextJs({
  convexUrl: process.env.NEXT_PUBLIC_CONVEX_URL!,
  convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
});
```

```typescript
import { createAuth } from "convex/auth";
import { setupFetchClient } from "@convex-dev/better-auth/react-start";
import { getCookie } from "@tanstack/react-start/server";
import { convexBetterAuthReactStart } from "@convex-dev/better-auth/react-start"; 

export const { fetchQuery, fetchMutation, fetchAction } =
  await setupFetchClient(createAuth, getCookie);

export const {
  handler,
  getToken,
  fetchAuthQuery,
  fetchAuthMutation,
  fetchAuthAction,
} = convexBetterAuthReactStart({
  convexUrl: process.env.VITE_CONVEX_URL!,
  convexSiteUrl: process.env.VITE_CONVEX_SITE_URL!,
});
```

--------------------------------

### Install dependencies for @convex-dev/better-auth@0.9

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-9

Install the required versions of the Better Auth component and Better Auth library. Use the exact versions shown to ensure compatibility with the 0.9 migration.

```bash
npm install @convex-dev/better-auth@0.9
npm install better-auth@1.3.34 --save-exact
```

--------------------------------

### ClientAuthBoundary for TanStack Start with useNavigate

Source: https://labs.convex.dev/better-auth/experimental

Client component wrapping AuthBoundary for TanStack Start, using useNavigate for redirect on unauthenticated access.

```typescript
"use client";

import { useNavigate } from "@tanstack/react-router";
import { AuthBoundary } from "@convex-dev/better-auth/react";
import { api } from "@/convex/_generated/api";
import { isAuthError } from "@/lib/utils";
import { authClient } from "@/lib/auth-client";

export const ClientAuthBoundary = ({ children }: PropsWithChildren) => {
  const navigate = useNavigate();
  return (
    <AuthBoundary
      authClient={authClient}
      // This can do anything you like, a redirect is typical.
      onUnauth={() => navigate({ to: "/sign-in" })}
      getAuthUserFn={api.auth.getAuthUser}
      isAuthError={isAuthError}
    >
      {children}
    </AuthBoundary>
  );
};
```

--------------------------------

### TanStack Start route wrapping with ClientAuthBoundary

Source: https://labs.convex.dev/better-auth/experimental

Route component for TanStack Start that checks authentication in beforeLoad and wraps the outlet with ClientAuthBoundary.

```typescript
import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
import { ClientAuthBoundary } from '@/lib/auth-client'

export const Route = createFileRoute("/_authed")({
  beforeLoad: ({ context }) => {
    if (!context.isAuthenticated) {
      console.log("redirecting to /sign-in");
      throw redirect({ to: "/sign-in" });
    }
  },
  component: () => {
    return (
      <ClientAuthBoundary>
        <Outlet />
      </ClientAuthBoundary>
    );
  },
});
```

--------------------------------

### Configure jwtCache for React Start (convexBetterAuthReactStart)

Source: https://labs.convex.dev/better-auth/experimental

Configure jwtCache for React Start server utilities. Enables JWT caching and uses the isAuthError utility to identify auth-related errors.

```typescript
import { convexBetterAuthReactStart } from "@convex-dev/better-auth/react-start";
import { isAuthError } from "@/lib/utils";

export const { fetchAuthQuery } = convexBetterAuthReactStart({
  convexUrl: process.env.VITE_CONVEX_URL!,
  convexSiteUrl: process.env.VITE_CONVEX_SITE_URL!,
  jwtCache: {
    enabled: true,
    isAuthError,
  },
});
```

--------------------------------

### Proxy auth requests in src/routes/api/auth/$.ts

Source: https://labs.convex.dev/better-auth/framework-guides/tanstack-start

Proxies auth requests from TanStack Start to the Convex deployment. Place in src/routes/api/auth/$.ts to handle GET and POST requests.

```typescript
import { createFileRoute } from '@tanstack/react-router'
import { handler } from '~/lib/auth-server'

export const Route = createFileRoute('/api/auth/$')({
  server: {
    handlers: {
      GET: ({ request }) => handler(request),
      POST: ({ request }) => handler(request),
    },
  },
})
```

--------------------------------

### Install @convex-dev/better-auth@0.12 and better-auth@1.6.15

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-12

Update the component and Better Auth. Better Auth must be on 1.6.9 or later in the 1.6.x line. Review breaking changes in Better Auth 1.6.

```bash
npm install @convex-dev/better-auth@^0.12.0
npm install better-auth@~1.6.15
```

--------------------------------

### Create Better Auth instance (auth.ts)

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Create a Better Auth instance with the Convex plugin and a sample query to get the current user. Some TypeScript errors may appear until the file is saved.

```typescript
import { createClient, type GenericCtx } from "@convex-dev/better-auth";
import { convex } from "@convex-dev/better-auth/plugins";
import { components } from "./_generated/api";
import { type 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({
    baseURL: siteUrl,
    database: authComponent.adapter(ctx),
    // Configure simple, non-verified email/password to get started
    emailAndPassword: {
      enabled: true,
      requireEmailVerification: false,
    },
    plugins: [
      // The Convex plugin is required for Convex compatibility
      convex({ authConfig }),
    ],
  })
}

// Example function for getting the current user
// Feel free to edit, omit, etc.
export const getCurrentUser = query({
  args: {},
  handler: async (ctx) => {
    return authComponent.getAuthUser(ctx);
  },
});
```

--------------------------------

### Define the Better Auth component (convex/betterAuth/convex.config.ts)

Source: https://labs.convex.dev/better-auth/features/local-install

Creates a convex.config.ts file in the convex/betterAuth directory to define the component and signal to Convex that this directory is a locally installed component.

```typescript
import { defineComponent } from "convex/server";

const component = defineComponent("betterAuth");

export default component;
```

--------------------------------

### TanStack Start: Update Vite config to bundle @convex-dev/better-auth

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-10

Add @convex-dev/better-auth to ssr.noExternal to avoid module resolution issues during SSR.

```ts
export default defineConfig({
  // ...other config
  ssr: {
    noExternal: ["@convex-dev/better-auth"],
  },
});
```

--------------------------------

### TanStack Start: Update router config with expectAuth

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-10

Set expectAuth: true on ConvexQueryClient to preserve authenticated data from server render. Also drop unused Wrap provider if present.

```tsx
export function getRouter() {
  const convexUrl = (import.meta as any).env.VITE_CONVEX_URL!;
  if (!convexUrl) {
    throw new Error("VITE_CONVEX_URL is not set");
  }
  const convexQueryClient = new ConvexQueryClient(convexUrl, {
    expectAuth: true, 
  });

  const queryClient: QueryClient = new QueryClient({
    defaultOptions: {
      queries: {
        queryKeyHashFn: convexQueryClient.hashFn(),
        queryFn: convexQueryClient.queryFn(),
      },
    },
  });
  convexQueryClient.connect(queryClient);

  const router = createTanStackRouter({
    routeTree,
    defaultPreload: "intent",
    defaultErrorComponent: DefaultCatchBoundary,
    defaultNotFoundComponent: () => <NotFound />,
    Wrap: ({ children }) => (
      <ConvexProvider client={convexQueryClient.convexClient}>
        {children}
      </ConvexProvider>
    ),
    context: { queryClient, convexQueryClient },
    scrollRestoration: true,
  });
  setupRouterSsrQueryIntegration({
    router,
    queryClient,
  });

  return router;
}
```

--------------------------------

### Regenerate schema with @better-auth/cli generate

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-11

Regenerate the schema when using Local Install after updating Better Auth. Run from the convex/betterAuth directory.

```bash
cd convex/betterAuth
npx @better-auth/cli generate -y
```

--------------------------------

### Pass initial token to ConvexBetterAuthProvider

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-10

Pass an initial token to `ConvexBetterAuthProvider` to speed up client authentication. Update `ConvexClientProvider` to accept an `initialToken` prop, then fetch the token on the server from the root layout and pass it to the provider. The TanStack Start root component uses `context.token` from the route context.

```tsx
export function ConvexClientProvider({
  children,
  initialToken, 
}: {
  children: ReactNode;
  initialToken?: string | null; 
}) {
  return (
    <ConvexBetterAuthProvider
      client={convex}
      authClient={authClient}
      initialToken={initialToken} 
    >
      {children}
    </ConvexBetterAuthProvider>
  );
}
```

```tsx
import { getToken } from "@/lib/auth-server"; 
import { ConvexClientProvider } from "./ConvexClientProvider";
import { PropsWithChildren } from "react";

export default async function RootLayout({ children }: PropsWithChildren) {
  const token = await getToken(); 
  return (
    <html>
      <body>
        <ConvexClientProvider>
        <ConvexClientProvider initialToken={token}>
          {children}
        </ConvexClientProvider>
      </body>
    </html>
  );
}
```

```tsx
function RootComponent() {
  const context = useRouteContext({ from: Route.id })
  return (
    <ConvexBetterAuthProvider
      client={context.convexQueryClient.convexClient}
      authClient={authClient}
      initialToken={context.token} 
    >
      <RootDocument>
        <Outlet />
      </RootDocument>
    </ConvexBetterAuthProvider>
  )
}
```

--------------------------------

### Basic Hono Configuration for Convex with Better Auth

Source: https://labs.convex.dev/better-auth/integrations/hono

Use this snippet to set up Hono as the HTTP router for Convex with Better Auth. It creates a Hono app that redirects the OpenID configuration endpoint and handles authentication routes. Requires the 'convex-helpers' package to be installed.

```typescript
import { Hono } from "hono";
import { HonoWithConvex, HttpRouterWithHono } from "convex-helpers/server/hono";
import { ActionCtx } from "./_generated/server";
import { createAuth } from "./auth";

const app: HonoWithConvex<ActionCtx> = new Hono();

// Redirect root well-known to api well-known
app.get("/.well-known/openid-configuration", async (c) => {
  return c.redirect("/api/auth/convex/.well-known/openid-configuration");
});

app.on(["POST", "GET"], "/api/auth/*", async (c) => {
  const auth = createAuth(c.env);
  return auth.handler(c.req.raw);
});

const http = new HttpRouterWithHono(app);

export default http;
```

--------------------------------

### TanStack Start: Update root route with getAuth and isAuthenticated

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-10

Use the new getAuth() server function and isAuthenticated context value. The beforeLoad handler sets the auth token on the server HTTP client during SSR.

```tsx
import { createServerFn } from "@tanstack/react-start";
import {
  fetchSession,
  getCookieName,
} from "@convex-dev/better-auth/react-start";
import { getCookie, getRequest } from "@tanstack/react-start/server"; 
import { getToken } from "@/lib/auth-server"; 

const fetchAuth = createServerFn({ method: "GET" }).handler(async () => {
  const { createAuth } = await import("@convex/auth");
  const { session } = await fetchSession(getRequest());
  const sessionCookieName = getCookieName(createAuth);
  const token = getCookie(sessionCookieName);
  return {
    userId: session?.user.id,
    token,
  };
});

const getAuth = createServerFn({ method: "GET" }).handler(async () => {
  return await getToken();
});

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient;
  convexQueryClient: ConvexQueryClient;
}>()({
  // ... other config
  beforeLoad: async (ctx) => {
    const token = await getAuth();

    // all queries, mutations and actions through TanStack Query will be
    // authenticated during SSR if we have a valid token
    if (token) {
      // During SSR only (the only time serverHttpClient exists),
      // set the auth token to make HTTP queries with.
      ctx.context.convexQueryClient.serverHttpClient?.setAuth(token);
    }

    return {
      isAuthenticated: !!token,
      token,
    };
  },
  component: RootComponent,
});
```

--------------------------------

### Call component function from parent with ctx.runQuery

Source: https://labs.convex.dev/better-auth/features/local-install

Call a component function from a parent component or app using ctx.runQuery with the component reference. This example shows how to invoke the someFunction defined in the component.

```typescript
import { query } from "./_generated/server";
import { components } from "./_generated/api";
import { v } from "convex/values";

export const someFunction = query({
  args: { sessionId: v.id("session") },
  handler: async (ctx, args) => {
    return await ctx.runQuery(components.betterAuth.someFile.someFunction, {
      sessionId: args.sessionId,
    });
  },
});
```

--------------------------------

### SvelteKit client-side authentication with Better Auth and Convex

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Complete SvelteKit page component that integrates Better Auth with Convex. It uses the auth client for sign-in, sign-up, sign-out, and token fetching, and uses the Convex query to get the current user. The component conditionally renders a sign-in/up form or a dashboard based on authentication state.

```svelte
<script lang="ts">
	import { authClient } from '$lib/auth-client';
	import { api } from '$convex/_generated/api';
	import { useQuery } from '@mmailaender/convex-svelte';
	import { useAuth } from '@mmailaender/convex-better-auth-svelte/svelte';

	let { data } = $props();

	// Auth state store
	const auth = useAuth();
	const isLoading = $derived(auth.isLoading);
	const isAuthenticated = $derived(auth.isAuthenticated);

	const currentUserResponse = useQuery(api.auth.getCurrentUser, () => (isAuthenticated ? {} : 'skip'));
	let user = $derived(currentUserResponse.data);

	// Sign in/up form state
	let showSignIn = $state(true);
	let name = $state('');
	let email = $state('');
	let password = $state('');

	// Handle form submission
	async function handlePasswordSubmit(event: Event) {
		event.preventDefault();

		try {
			if (showSignIn) {
				await authClient.signIn.email(
					{ email, password },
					{
						onError: (ctx) => {
							alert(ctx.error.message);
						}
					}
				);
			} else {
				await authClient.signUp.email(
					{ name, email, password },
					{
						onError: (ctx) => {
							alert(ctx.error.message);
						}
					}
				);
			}
		} catch (error) {
			console.error('Authentication error:', error);
		}
	}

	// Sign out function
	async function signOut() {

		const result = await authClient.signOut();
		if(result.error) {
			console.error('Sign out error:', result.error);
		}
	}

	// Toggle between sign in and sign up
	function toggleSignMode() {
		showSignIn = !showSignIn;
		// Clear form fields when toggling
		name = '';
		email = '';
		password = '';
	}

	// Demo: Fetch access token
	let accessToken = $state<string | null>(null);
	let tokenLoading = $state(false);

	async function fetchToken() {
		tokenLoading = true;
		try {
			const token = await auth.fetchAccessToken({ forceRefreshToken: true });
			accessToken = token;
		} catch (error) {
			console.error('Error fetching access token:', error);
			accessToken = 'Error fetching token';
		} finally {
			tokenLoading = false;
		}
	}
</script>

<div class="flex h-screen flex-col items-center justify-center bg-gray-50">
	{#if isLoading}
		<div class="text-lg text-gray-600">Loading...</div>
	{:else if !isAuthenticated}
		<!-- Sign In Component -->
		<div class="flex w-full max-w-md flex-col gap-4 rounded-lg bg-white p-6 shadow-md">
			<h2 class="mb-6 text-center text-2xl font-bold text-gray-800">
				{showSignIn ? 'Sign In' : 'Sign Up'}
			</h2>

			<form onsubmit={handlePasswordSubmit} class="flex flex-col gap-4">
				{#if !showSignIn}
					<input
						bind:value={name}
						placeholder="Name"
						required
						class="rounded-md border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500 focus:outline-none"
					/>
				{/if}
				<input
					type="email"
					bind:value={email}
					placeholder="Email"
					required
					class="rounded-md border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500 focus:outline-none"
				/>
				<input
					type="password"
					bind:value={password}
					placeholder="Password"
					required
					class="rounded-md border border-gray-300 px-4 py-2 focus:border-transparent focus:ring-2 focus:ring-blue-500 focus:outline-none"
				/>
				<button
					type="submit"
					class="cursor-pointer rounded-md bg-blue-600 px-4 py-2 text-white transition-colors hover:bg-blue-700 focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:outline-none"
				>
					{showSignIn ? 'Sign in' : 'Sign up'}
				</button>
			</form>

			<p class="mt-4 text-center text-gray-600">
				{showSignIn ? "Don't have an account? " : 'Already have an account? '}
				<button
					type="button"
					onclick={toggleSignMode}
					class="cursor-pointer border-none bg-transparent text-blue-600 underline hover:text-blue-800"
				>
					{showSignIn ? 'Sign up' : 'Sign in'}
				</button>
			</p>
		</div>
	{:else if isAuthenticated}
		<!-- Dashboard Component -->
		<div class="w-full max-w-md rounded-lg bg-white p-6 text-center shadow-md">
			<div class="mb-4 text-xl font-semibold text-gray-800">
				Hello {user?.name}!
			</div>

```

--------------------------------

### Calling the Convex mutation from a server action

Source: https://labs.convex.dev/better-auth/framework-guides/tanstack-start

Server action that calls the Convex mutation via fetchAuthMutation. This allows Better Auth methods to run in a Convex function from TanStack Start server code.

```ts
import { createServerFn } from "@tanstack/react-start";
import { fetchAuthMutation } from "@/lib/auth-server";
import { api } from "../../convex/_generated/api";

export const updatePassword = createServerFn({ method: "POST" }).handler(
  async ({ data: { currentPassword, newPassword } }) => {
    await fetchAuthMutation(api.users.updatePassword, {
      currentPassword,
      newPassword,
    });
  }
);
```

--------------------------------

### Update Better Auth instance with crossDomain plugin

Source: https://labs.convex.dev/better-auth/framework-guides/expo

Update the Better Auth instance in convex/auth.ts to add the site URL and the cross-domain plugin. Requires setting SITE_URL as described in the React guide.

```typescript
import { createClient, type GenericCtx } from "@convex-dev/better-auth";
import {
  convex,
  crossDomain, 
} from "@convex-dev/better-auth/plugins";
import { betterAuth } from "better-auth/minimal";
import { expo } from "@better-auth/expo";
import { components } from "./_generated/api";
import { DataModel } from "./_generated/dataModel";
import { query } from "./_generated/server";
import authConfig from "./auth.config";

// 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);

const siteUrl = process.env.SITE_URL!; 

export const createAuthOptions = (ctx: GenericCtx<DataModel>) =>
  ({
    trustedOrigins: [siteUrl, "your-scheme://"], 
    database: authComponent.adapter(ctx),
    emailAndPassword: {
      enabled: true,
      requireEmailVerification: false,
    },
    plugins: [
      expo(),
      convex({ authConfig }),
      crossDomain({ siteUrl }), 
    ],
  }) satisfies BetterAuthOptions;
```

--------------------------------

### Set up Convex client provider (+layout.svelte)

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Initialize the Convex client with auth in your app. `createSvelteAuthClient` includes `setupConvex()` from `@mmailaender/convex-svelte`.

```svelte
<script lang="ts">
  import '../app.css';
  import favicon from '$lib/assets/favicon.svg';
  import { createSvelteAuthClient } from '@mmailaender/convex-better-auth-svelte/svelte'; 
  import { authClient } from '$lib/auth-client'; 

  createSvelteAuthClient({ authClient }); 

  let { children } = $props();
</script>

<svelte:head>
  <link rel="icon" href={favicon} />
</svelte:head>

{@render children?.()}
```

--------------------------------

### Update route handlers for Next.js and TanStack Start

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-10

Update route handlers to use the new handler. The Next.js route uses `nextJsHandler` from `@convex-dev/better-auth/nextjs`; the TanStack Start route uses `reactStartHandler` from `@convex-dev/better-auth/react-start`. Both examples show the new handler replacing the previous one.

```typescript
import { nextJsHandler } from "@convex-dev/better-auth/nextjs"; 
import { handler } from "@/lib/auth-server"; 

export const { GET, POST } = nextJsHandler(); 
export const { GET, POST } = handler; 
```

```typescript
import { createFileRoute } from '@tanstack/react-router'
import { reactStartHandler } from '@convex-dev/better-auth/react-start'
import { handler } from '~/lib/auth-server'

export const Route = createFileRoute('/api/auth/$')({
  server: {
    handlers: {
      GET: ({ request }) => reactStartHandler(request),
      POST: ({ request }) => reactStartHandler(request),
      GET: ({ request }) => handler(request),
      POST: ({ request }) => handler(request),
    },
  },
})
```

--------------------------------

### Set baseURL in betterAuth() options

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-12

Add baseURL to betterAuth() options when using the cross-domain plugin (e.g., Vite SPA, Expo Web). Without it, Better Auth 1.6 logs a 'Base URL could not be determined' warning on every request. Next.js and TanStack Start setups already set baseURL and are not affected.

```javascript
betterAuth({
  baseURL: process.env.CONVEX_SITE_URL, 
  // ...
});
```

--------------------------------

### Update adapter exports (Local Install only)

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-9/migrate-userid/userid-in-app-table

If using Local Install, update the adapter exports to include the `migrationRemoveUserId` function.

```typescript
export const {
  create,
  findOne,
  findMany,
  updateOne,
  updateMany,
  deleteOne,
  deleteMany,
  migrationRemoveUserId, 
} = createApi(schema, createAuth);
```

--------------------------------

### Set up SvelteKit route handlers (+server.ts)

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Proxy auth requests from the SvelteKit server to the Convex deployment.

```typescript
import { createSvelteKitHandler } from '@mmailaender/convex-better-auth-svelte/sveltekit';

export const { GET, POST } = createSvelteKitHandler();
```

--------------------------------

### Create Better Auth client instance (auth-client.ts)

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Create a Better Auth client instance for SvelteKit, including the Convex client plugin.

```typescript
import { createAuthClient } from 'better-auth/svelte';
import { convexClient } from "@convex-dev/better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [convexClient()],
});
```

--------------------------------

### Set up root route with ConvexBetterAuthProvider

Source: https://labs.convex.dev/better-auth/framework-guides/tanstack-start

Wraps the application root with ConvexBetterAuthProvider and makes auth available in loaders. Place in src/routes/__root.tsx to enable SSR authentication.

```typescript
/// <reference types="vite/client" />
import {
  HeadContent,
  Outlet,
  Scripts,
  createRootRouteWithContext,
  useRouteContext,
} from '@tanstack/react-router'
import * as React from 'react'
import { createServerFn } from '@tanstack/react-start'
import { ConvexBetterAuthProvider } from '@convex-dev/better-auth/react'
import type { ConvexQueryClient } from '@convex-dev/react-query'
import type { QueryClient } from '@tanstack/react-query'
import appCss from '~/styles/app.css?url'
import { authClient } from '~/lib/auth-client'
import { getToken } from '~/lib/auth-server'

// Get auth information for SSR using available cookies
const getAuth = createServerFn({ method: 'GET' }).handler(async () => {
  return await getToken()
})

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient
  convexQueryClient: ConvexQueryClient
}>()({
  head: () => ({
    meta: [
      {
        charSet: 'utf-8',
      },
      {
        name: 'viewport',
        content: 'width=device-width, initial-scale=1',
      },
    ],
    links: [
      { rel: 'stylesheet', href: appCss },
      { rel: 'icon', href: '/favicon.ico' },
    ],
  }),
  beforeLoad: async (ctx) => {
    const token = await getAuth()

    // all queries, mutations and actions through TanStack Query will be
    // authenticated during SSR if we have a valid token
    if (token) {
      // During SSR only (the only time serverHttpClient exists),
      // set the auth token to make HTTP queries with.
      ctx.context.convexQueryClient.serverHttpClient?.setAuth(token)
    }

    return {
      isAuthenticated: !!token,
      token,
    }
  },
  component: RootComponent,
})

function RootComponent() {
  const context = useRouteContext({ from: Route.id }) 
  return (
    <ConvexBetterAuthProvider
      client={context.convexQueryClient.convexClient}
      authClient={authClient}
      initialToken={context.token}
    >
      <RootDocument>
        <Outlet />
      </RootDocument>
    </ConvexBetterAuthProvider>
  )
}

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className="dark">
      <head>
        <HeadContent />
      </head>
      <body className="bg-neutral-950 text-neutral-50">
        {children}
        <Scripts />
      </body>
    </html>
  )
}
```

--------------------------------

### Run addAuthId migration in development

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-9/migrate-userid/userid-in-app-table

Runs the `addAuthId` migration to backfill the `authId` field for previously existing users in the development deployment. Requires the Convex dev server to be running.

```bash
npx convex run migrations:addAuthId
```

--------------------------------

### Run addAuthId migration in production

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-9/migrate-userid/userid-in-app-table

Runs the `addAuthId` migration against the production deployment using the `--prod` flag. Can also be run from the production deployment dashboard.

```bash
npx convex run migrations:addAuthId --prod
```

--------------------------------

### Set environment variables (SITE_URL)

Source: https://labs.convex.dev/better-auth/framework-guides/tanstack-start

Add your site URL to your Convex deployment.

```bash
npx convex env set SITE_URL http://localhost:3000
```

--------------------------------

### Set up Convex client provider with ConvexBetterAuthProvider

Source: https://labs.convex.dev/better-auth/framework-guides/next

Wrap your app with ConvexBetterAuthProvider instead of ConvexProvider. It requires a ConvexReactClient instance, the authClient from @/lib/auth-client, and an optional initialToken for SSR.

```tsx
"use client";

import { ReactNode } from "react";
import { ConvexReactClient } from "convex/react";
import { authClient } from "@/lib/auth-client";
import { ConvexBetterAuthProvider } from "@convex-dev/better-auth/react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({
  children,
  initialToken,
}: {
  children: ReactNode;
  initialToken?: string | null;
}) {
  return (
    <ConvexBetterAuthProvider
      client={convex}
      authClient={authClient}
      initialToken={initialToken}
    >
      {children}
    </ConvexBetterAuthProvider>
  );
}
```

--------------------------------

### Get auth state in layout server with getAuthState

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Use in src/routes/+layout.server.ts to get the authentication state during SSR. Call getAuthState with no arguments when withServerConvexToken is set up in your hook; it reads the token automatically and is synchronous.

```typescript
import type { LayoutServerLoad } from "./$types";
import { getAuthState } from "@mmailaender/convex-better-auth-svelte/sveltekit";

export const load: LayoutServerLoad = () => {
  return { authState: getAuthState() }; // synchronous, no await needed
};
```

--------------------------------

### Create Better Auth client instance

Source: https://labs.convex.dev/better-auth/framework-guides/expo

Create a Better Auth client instance for interacting with the Better Auth server from your client.

```typescript
import { createAuthClient } from "better-auth/react";
import { convexClient } from "@convex-dev/better-auth/client/plugins";
import { expoClient } from '@better-auth/expo/client'
import Constants from 'expo-constants'
import * as SecureStore from 'expo-secure-store'

export const authClient = createAuthClient({
  baseURL: process.env.EXPO_PUBLIC_CONVEX_SITE_URL,
  plugins: [
    expoClient({
      scheme: Constants.expoConfig?.scheme as string,
      storagePrefix: Constants.expoConfig?.scheme as string,
      storage: SecureStore,
    }),
    convexClient(),
  ],
});
```

--------------------------------

### Run convex dev

Source: https://labs.convex.dev/better-auth

Run the Convex CLI in development mode to initialize your deployment and keep generated types current.

```bash
npx convex dev
```

--------------------------------

### Set up Convex client provider in app/_layout.tsx

Source: https://labs.convex.dev/better-auth/framework-guides/expo

Wrap the app layout with ConvexBetterAuthProvider, passing the Convex client and authClient. Optionally set expectAuth to true to pause queries until authenticated.

```tsx
import { StrictMode } from "react";
import { Slot } from "expo-router";
import {
  ConvexReactClient,
  ConvexProvider, 
} from "convex/react";
import { ConvexBetterAuthProvider } from "@convex-dev/better-auth/react"; 
import { authClient } from "@/lib/auth-client"; 

const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL as string, {
  // Optionally pause queries until the user is authenticated
  expectAuth: true, 
  unsavedChangesWarning: false, 
});

export default function MyLayout() {
  return (
    <StrictMode>
      <ConvexProvider client={convex}>
      <ConvexBetterAuthProvider client={convex} authClient={authClient}>
        <Slot />
      </ConvexBetterAuthProvider>
      </ConvexProvider>
    </StrictMode>
  )
}
```

--------------------------------

### Update component registration (convex/convex.config.ts)

Source: https://labs.convex.dev/better-auth/features/local-install

Updates the component registration to use the locally installed component instead of the default package import.

```typescript
import { defineApp } from "convex/server";
import betterAuth from "@convex-dev/better-auth/convex.config"; 
import betterAuth from "./betterAuth/convex.config"; 

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

export default app;
```

--------------------------------

### Generate the schema with Better Auth CLI

Source: https://labs.convex.dev/better-auth/features/local-install

Runs the Better Auth CLI to generate the schema for the component. Must be run from the convex/betterAuth directory.

```bash
cd convex/betterAuth
npx auth generate
```

--------------------------------

### getAnyUserById() - Fetch user by ID

Source: https://labs.convex.dev/better-auth/api/component-client

Returns a user by their Better Auth user id. The example shows a Convex query that calls getAnyUserById with the provided id.

```typescript
import { query } from "./_generated/server";
import { v } from "convex/values";
import { authComponent } from "./auth";

export const getUser = query({
  args: { id: v.id("user") },
  handler: async (ctx, args) => {
    return authComponent.getAnyUserById(ctx, args.id);
  },
});
```

--------------------------------

### TanStack Start: Reload on sign out

Source: https://labs.convex.dev/better-auth/migrations/migrate-to-0-10

Update signOut functions to reload the page, allowing expectAuth to work correctly for the next sign in. For authenticated routes, this can replace a redirect.

```ts
export const handleSignOut = async () => {
  const navigate = useNavigate();
  await authClient.signOut({
    fetchOptions: {
      onSuccess: () => {
        navigate({ to: "/" }); 
        location.reload(); 
      },
    },
  });
};
```

--------------------------------

### Custom JWT payload

Source: https://labs.convex.dev/better-auth/api/convex-plugin

Custom JWT payload example. Sets expiration to 30 minutes and defines a custom payload. sessionId and iat are always added automatically.

```typescript
convex({
  authConfig,
  jwt: {
    expirationSeconds: 60 * 30, // 30 minutes
    definePayload: ({ user, session }) => ({
      name: user.name,
      email: user.email,
      role: user.role,
      sessionId: session.id,
    }),
  },
});
```

--------------------------------

### Set up route handlers in app/api/auth/[...all]/route.ts

Source: https://labs.convex.dev/better-auth/framework-guides/next

Set up route handlers to proxy auth requests from Next.js to your Convex deployment.

```typescript
import { handler } from "@/lib/auth-server";

export const { GET, POST } = handler;
```

--------------------------------

### Type definition for event.locals.token (src/app.d.ts)

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Adds the `token` property to the `App.Locals` interface, enabling TypeScript support for `event.locals.token` in server code. This is required for the hook setup to provide type safety.

```typescript
declare global {
  namespace App {
    interface Locals {
      token: string | undefined; 
    }
  }
}
```

--------------------------------

### adapter()

Source: https://labs.convex.dev/better-auth/api/component-client

Returns the Convex database adapter for use in Better Auth options.

```APIDOC
## `adapter()`

### Description
Returns the Convex database adapter for use in Better Auth options.

### Method
`adapter()`

### Parameters
None

### Returns
- **ConvexDatabaseAdapter** - The Convex database adapter to pass to Better Auth options.

### Example
```typescript
import { createClient } from "@convex-dev/better-auth";
import { components } from "./_generated/api";
import { type GenericCtx } from "./_generated/server";
import { DataModel } from "./_generated/dataModel";

export const authComponent = createClient<DataModel>(components.betterAuth);

export const createAuth = (ctx: GenericCtx<DataModel>) => {
  return betterAuth({
    database: authComponent.adapter(ctx),
  });
});
```
```

--------------------------------

### Customize convex functionsDir in convex.json

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Configure the Convex functions directory to be under src/ in the convex.json file. This is required because SvelteKit does not like referencing code outside of source.

```json
{
  "functions": "src/convex/"
}
```

--------------------------------

### Google sign-in authorized redirect URI

Source: https://labs.convex.dev/better-auth/framework-guides/react

For social sign-in in React SPAs, the authorized redirect URI is based on your Convex site URL instead of your application domain. Example with Google sign-in.

```text
https://adjective-animal-123.convex.site/api/auth/callback/google
```

--------------------------------

### Social sign-in authorized origin and redirect URI

Source: https://labs.convex.dev/better-auth/framework-guides/expo

For social sign-in with Expo, use the Convex site URL as the authorized origin and redirect URI. Example shows Google sign-in callback URI.

```text
// authorized origin
https://adjective-animal-123.convex.site

// authorized redirect URI
https://adjective-animal-123.convex.site/api/auth/callback/google
```

--------------------------------

### Configure TanStack server utilities (src/lib/auth-server.ts)

Source: https://labs.convex.dev/better-auth/framework-guides/tanstack-start

Configure a set of helper functions for authenticated SSR, server functions, and route handlers.

```typescript
import { convexBetterAuthReactStart } from '@convex-dev/better-auth/react-start'

export const {
  handler,
  getToken,
  fetchAuthQuery,
  fetchAuthMutation,
  fetchAuthAction,
} = convexBetterAuthReactStart({
  convexUrl: process.env.VITE_CONVEX_URL!,
  convexSiteUrl: process.env.VITE_CONVEX_SITE_URL!,
  // Optional, defaults to "/api/auth"
  basePath: "/custom/auth/path",
})
```

--------------------------------

### Add internal action to get latest JWKS

Source: https://labs.convex.dev/better-auth/experimental

Add this internal action to convex/auth.ts to retrieve the latest JWKS. It must be a mutation because a new key may be written. The method is added by the Convex Better Auth plugin and is available via auth.api only.

```typescript
export const getLatestJwks = internalAction({
  args: {},
  handler: async (ctx) => {
    const auth = createAuth(ctx);
    // This method is added by the Convex Better Auth plugin and is
    // available via `auth.api` only, not exposed as a route.
    return await auth.api.getLatestJwks();
  },
});
```

--------------------------------

### getAuth() - Call Better Auth API with headers

Source: https://labs.convex.dev/better-auth/api/component-client

Provides both the auth object and headers for calling Better Auth API endpoints from a Convex mutation. The example shows a changePassword mutation that uses getAuth to obtain auth and headers, then calls auth.api.changePassword.

```typescript
import { mutation } from "./_generated/server";
import { v } from "convex/values";
import { createAuth, authComponent } from "./auth";

export const changePassword = mutation({
  args: {
    newPassword: v.string(),
    currentPassword: v.string(),
  },
  handler: async (ctx, args) => {
    const { auth, headers } = await authComponent.getAuth(createAuth, ctx);
    await auth.api.changePassword({
      body: {
        newPassword: args.newPassword,
        currentPassword: args.currentPassword,
      },
      headers,
    });
  },
});
```

--------------------------------

### Generate schema with npx auth generate

Source: https://labs.convex.dev/better-auth/local-install

Run this command from the convex/betterAuth directory to generate the schema for the component using the Better Auth CLI.

```bash
cd convex/betterAuth
auth generate
```

--------------------------------

### Make all requests authenticated with expectAuth

Source: https://labs.convex.dev/better-auth/framework-guides/sveltekit

Use this when your app is essentially members-only and almost all data requires authentication. By enabling expectAuth, all Convex queries and mutations created through createSvelteAuthClient will automatically include the auth token and will not run until the user is authenticated.

```svelte
import { createSvelteAuthClient } from "@mmailaender/convex-better-auth-svelte/svelte";
import { authClient } from "$lib/auth-client";

createSvelteAuthClient({
  authClient,
  options: {
    expectAuth: true,
  },
});
```

--------------------------------

### Add CORS Support to Hono Configuration

Source: https://labs.convex.dev/better-auth/integrations/hono

Required for client-only or SPA installations like React/Vite. This snippet adds CORS middleware to the Hono app, allowing cross-origin requests with credentials. It configures allowed origins, headers, methods, and exposes the Better Auth cookie header.

```typescript
import { Hono } from "hono";
import { HonoWithConvex, HttpRouterWithHono } from "convex-helpers/server/hono";
import { cors } from "hono/cors"; 
import { ActionCtx } from "./_generated/server";
import { createAuth } from "../lib/auth";

const app: HonoWithConvex<ActionCtx> = new Hono();

app.use(
  "/api/auth/*",
  cors({
    origin: process.env.SITE_URL,
    allowHeaders: ["Content-Type", "Authorization", "Better-Auth-Cookie"],
    allowMethods: ["GET", "POST", "OPTIONS"],
    exposeHeaders: ["Content-Length", "Set-Better-Auth-Cookie"],
    maxAge: 600,
    credentials: true,
  })
);

// ...
```

--------------------------------

### Generate Better Auth schema to secondary file with --output

Source: https://labs.convex.dev/better-auth/features/local-install

Generate the schema to a secondary file so custom indexes can be added without being overwritten on regeneration.

```bash
cd convex/betterAuth
npx auth generate --output generatedSchema.ts
```
Tokens:
Raw