repository·main·Indexed 18 days ago
https://github.com/get-convex/better-authAn integration between Convex and Better Auth that enables developers to implement authentication systems, including Email/Password, OAuth, and 2FA, within Convex-backed applications.
While most Better Auth concepts apply to Convex, there are two key differences to keep in mind:
Server-side authentication: Because Convex functions run over websockets and cannot return HTTP responses or set cookies, you cannot use server-side sign-in/out functions. All signing in, signing up, and signing out must be performed from the client using authClient.signIn.* methods.
Schemas and migrations: The Better Auth CLI for schema generation and migrations only applies if you are using a local install. For all other projects, you must use the default schema provided by the Better Auth component, which is preconfigured with supported plugins and cannot be altered.
You can handle authenticated Convex requests in two ways depending on your application's access model:
Use this if your app has both public and private content. Use useAuth to check isAuthenticated and return 'skip' to the useQuery hook if the user is not logged in.
Use this if almost all data requires authentication. Configure createSvelteAuthClient with options: { expectAuth: true }. This ensures all queries/mutations automatically include the auth token and will not execute until the user is authenticated.
// Option 1: Conditional
const auth = useAuth();
const memberOnlyPosts = useQuery(api.posts.getMemberOnlyPosts, () =>
auth.isAuthenticated ? {} : "skip"
);
// Option 2: Global
createSvelteAuthClient({
authClient,
options: {
expectAuth: true,
},
});Triggers provide a Convex-first way to run mutations in response to changes in your Better Auth schema. Unlike standard Better Auth databaseHooks, Triggers run within the same transaction as the original operation. This ensures atomicity: if a trigger throws an error, the database operation that triggered it will fail and roll back.
Important Transactional Note: A single Better Auth endpoint or auth.api call can perform multiple database interactions. While throwing an error in a trigger will fail the specific database operation that triggered it, any previous operations within that same API call may still commit.
// Triggers run in the same transaction as the original operation.
// Throwing an error in a trigger will stop the original operation from committing.When using social sign-in (e.g., Google) with a React SPA, the authorized redirect URI must be based on your Convex site URL rather than your application's domain.
Example for Google sign-in:
https://<your-deployment-name>.convex.site/api/auth/callback/google
The integration is framework agnostic and supports a wide range of popular frontend and backend frameworks, including:
The subject property in the identity token no longer refers to your application's user ID; it now refers to the Better Auth user ID.
To get your application user's ID, use authComponent.getAuthUser(ctx), which returns the full Better Auth user object.
Note on Error Handling:
authComponent.getAuthUser(ctx) throws an error if the user is not found.authComponent.safeGetAuthUser(ctx) if you want the previous behavior where it returns null instead of throwing.// Use getAuthUser for required auth
const userId = (await authComponent.getAuthUser(ctx))?.userId;
// Use safeGetAuthUser for optional auth
const userMetadata = await authComponent.safeGetAuthUser(ctx);
if (!userMetadata) {
return null;
}Functions defined within a component directory can access the component's tables directly. These functions can be called from outside the component using ctx.runQuery, ctx.runMutation, or ctx.runAction.
public. Only functions defined in the main app/component are internet-facing.returns validator in the component function so that the return type can be correctly inferred by the caller.internalQuery or internalMutation within a component are not accessible from outside the component.import { query } from "./_generated/server";
import { doc } from "convex-helpers/validators";
import schema from "./schema";
import { v } from "convex/values";
// This is accessible from outside the component
export const someFunction = query({
args: { sessionId: v.id("session") },
// Add a return validator so the return value is typed when
// called from outside the component.
returns: v.union(v.null(), doc(schema, "session")),
handler: async (ctx, args) => {
return await ctx.db.get(args.sessionId);
},
});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,
});
},
});To use Convex with Better Auth, follow these general setup steps:
convex dev: Start the Convex development server to sync your schema and functions.Installation steps vary significantly depending on whether you are using a Single Page Application (SPA), a meta-framework, or a mobile environment.
When expectAuth: true is enabled, it only affects the state before the initial authentication. If a user signs out and signs back in, authenticated queries may be called before the authentication state is ready, causing errors.
Recommendation: Reload the page on sign out. This ensures the application state is reset correctly. For apps with authentication-based redirects, the reload will trigger the necessary unauthenticated redirect.
import { authClient } from "~/lib/auth-client";
const handleSignOut = async () => {
await authClient.signOut({
fetchOptions: {
onSuccess: () => {
location.reload();
},
},
});
};import { authClient } from "~/lib/auth-client";
const handleSignOut = async () => {
await authClient.signOut({
fetchOptions: {
onSuccess: () => {
location.reload();
},
},
});
};You can invoke Better Auth server-side auth.api methods within Convex mutations or actions. Since many of these methods require an authenticated user, you must pass the request headers so session cookies can be parsed and validated.
Use the authComponent.getAuth(createAuth, ctx) method to conveniently retrieve both the auth object and the necessary headers from the Convex context.
export const updateUserPassword = mutation({
args: {
currentPassword: v.string(),
newPassword: v.string(),
},
handler: async (ctx, args) => {
// The `getAuth` method provides both the auth object and headers for convenience.
const { auth, headers } = await authComponent.getAuth(createAuth, ctx);
await auth.api.changePassword({
body: {
currentPassword: args.currentPassword,
newPassword: args.newPassword,
},
headers,
});
},
});