better-auth-convex is a JavaScript/TypeScript library designed to integrate the better-auth authentication solution directly into a Convex application's schema, offering an alternative to the official component-based approach. The current stable version is 0.5.1, with development showing a consistent release cadence of patch and minor updates. Its primary differentiation lies in placing authentication tables within the application's own schema, allowing for direct database access without the latency associated with ctx.runQuery or ctx.runMutation overhead. This approach also ensures a unified context, enabling auth triggers to directly access and modify application tables transactionally, and provides full TypeScript inference across the entire schema. This library requires better-auth and @convex-dev/better-auth as peer dependencies and is primarily used in a Node.js/Convex environment.
npm install better-auth-convexVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates the core setup for `better-auth-convex`, including defining the `auth.config.ts` and `auth.ts` files. It shows how to create an `authClient` with custom `user` and `session` triggers for lifecycle management, such as setting a default username, creating a personal organization for new users, and cleaning up data upon user deletion. It also illustrates how to combine these with `betterAuth` and Convex-specific plugins.
Before deploying, write and execute a migration script to transfer any existing authentication data from the component-scoped tables to your application's database tables.
Consult the official `@convex-dev/better-auth` migration guide for version 0.10 at `https://labs.convex.dev/better-auth/migrations/migrate-to-0-10` and adapt your code accordingly.
Update your Convex internal API definitions and any calling code to reflect `getLatestJwks` as an internal action rather than a mutation. For example, change `internal.auth.getLatestJwks` to `internal.auth.action.getLatestJwks` if you follow the recommended API structure.
Pass the `skipValidation: true` option to `createApi` when creating your internal API functions (e.g., `createApi({ ..., skipValidation: true })`) to use generic `v.any()` validators and reduce bundle size.Upgrade `better-auth-convex` to version `0.4.6` or later to ensure the `dist` folder and compiled assets are properly included in the npm package.
For `createSchema`, explicitly import it from the dedicated subpath: `import { createSchema } from 'better-auth-convex/schema'`. Ensure you are using `better-auth-convex@0.4.6` or a newer version where this fix was implemented.