Registry / auth-security / better-auth-convex

better-auth-convex

JSON →
library0.5.1jsnpmunverified

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-convex
INSTALL
IMPORT
SIG · BETTER-AUTH-CONVEX
B
better-auth-convex
auth-securityjavascriptv0.5.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createClient
✓ import { createClient } from 'better-auth-convex'
✗ const { createClient } = require('better-auth-convex')
ESM-only usage is standard for modern Convex development, especially when shipping TypeScript types. Avoid CommonJS `require` syntax.
createApi
✓ import { createApi } from 'better-auth-convex'
✗ const { createApi } = require('better-auth-convex')
This function is used to create an internal API handler for authentication operations. It is designed for ESM environments.
AuthFunctions
✓ import type { AuthFunctions } from 'better-auth-convex'
✗ import { AuthFunctions } from 'better-auth-convex'
AuthFunctions is a TypeScript type. Always use `import type` to prevent it from being bundled as a runtime import, which can lead to errors or larger bundle sizes.
createSchema
✓ import { createSchema } from 'better-auth-convex/schema'
✗ import { createSchema } from 'better-auth-convex'
Prior to v0.4.6, `createSchema` was exported directly from the main package. Since v0.4.6, it was moved to a dedicated subpath to resolve Convex bundler errors related to Node.js `path` module imports.

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.

// convex/auth.config.ts import { getAuthConfigProvider } from "@convex-dev/better-auth/auth-config"; import type { AuthConfig } from "convex/server"; export default { providers: [getAuthConfigProvider({ jwks: process.env.JWKS ?? '' })], } satisfies AuthConfig; // convex/auth.ts import { betterAuth } from "better-auth"; import { convex } from "@convex-dev/better-auth/plugins"; import { admin, organization } from "better-auth/plugins"; // Optional plugins import { type AuthFunctions, createClient, createApi } from "better-auth-convex"; import { internal } from "./_generated/api"; import type { MutationCtx, QueryCtx, GenericCtx } from "./_generated/server"; import type { DataModel } from "./_generated/dataModel"; import schema from "./schema"; // YOUR app schema with auth tables import authConfig from "./auth.config"; // 1. Internal API functions for auth operations const authFunctions: AuthFunctions = internal.auth; // 2. Auth client with triggers that run in your app context export const authClient = createClient<DataModel, typeof schema>({ authFunctions, schema, triggers: { user: { beforeCreate: async (_ctx, data) => { const username = data.username?.trim() || data.email?.split("@")[0] || `user-${Date.now()}`; return { ...data, username }; }, onCreate: async (ctx, user) => { const orgId = await ctx.db.insert("organization", { name: `${user.name}'s Workspace`, slug: `personal-${user._id}` }); await ctx.db.patch(user._id, { personalOrganizationId: orgId }); }, beforeDelete: async (ctx, user) => { if (user.personalOrganizationId) { await ctx.db.delete(user.personalOrganizationId); } return user; } }, session: { onCreate: async (ctx, session) => { // Handle session creation logic, e.g., logging or analytics } } } }); export const auth = betterAuth< typeof schema, MutationCtx<DataModel>, QueryCtx<DataModel>, GenericCtx<DataModel> >({ authConfig, authClient, plugins: [ convex({ internal, authClient, schema }), admin({ authClient }), organization({ authClient }) ] });
Debug
Known issues
breakingThis package fundamentally alters where Better Auth tables are stored, moving them from a component schema into your main application schema. This requires a manual migration script if you are moving an existing `@convex-dev/better-auth` component-based deployment to `better-auth-convex`.
fix
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.
affects: >=0.1.0
breakingVersion 0.5.0 introduces compatibility with `@convex-dev/better-auth@0.10.4` and `better-auth@1.4.7`. Migrating to this version requires following the upstream migration guide for `@convex-dev/better-auth@0.10` to ensure API consistency.
fix
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.
affects: >=0.5.0
breakingIn version 0.5.1, the `getLatestJwks` function was changed from an internal mutation to an internal action. This affects how it is called and defined in your Convex internal API.
fix
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.
affects: >=0.5.1
gotchaBy default, internal API functions generated by `createApi` include typed validators, which can significantly increase your bundle size, especially with complex schemas. For internal functions where type validation is less critical or handled by other mechanisms, this can lead to larger deployment bundles and slower build times.
fix
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.
affects: >=0.4.9
Errors
Common errors & fixes
Module not found: Error: Can't resolve 'better-auth-convex' in '...'
The `dist` folder, which contains the compiled JavaScript output, was missing from the published npm package in some earlier versions, preventing bundlers from resolving the package correctly.
fix
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.
Convex bundler error: 'path' module not found
Prior to `v0.4.6`, the `createSchema` utility was directly exported from the main package entry point, which caused issues with the Convex bundler trying to resolve Node.js-specific built-in modules like `path` that are not available in the Convex environment.
fix
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.
Upgrade
Version history
0.5.1latest on npm
Audit
Dependencies
@convex-dev/better-authrequiredCore authentication logic dependency, specified as a peer dependency.
better-authrequiredCore authentication library, installed alongside and used by the integration.
Agent activity
30 hits · last 30 days
node
24
OpenAI (training)
1
Resources
better-auth-convex — npm install better-auth-convex · libregistry