Server

bun add better-auth@1.4.9 @convex-dev/better-auth better-convex hono

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;

import { betterAuth, type BetterAuthOptions } from 'better-auth';
import { convex } from '@convex-dev/better-auth/plugins';
import { admin } from 'better-auth/plugins';
import { createClient, createApi, type AuthFunctions } from 'better-convex/auth';
import { internal } from './_generated/api';
import type { MutationCtx, QueryCtx } from './_generated/server';
import type { DataModel } from './_generated/dataModel';
import schema from './schema';
import authConfig from './auth.config';

type GenericCtx = QueryCtx | MutationCtx | ActionCtx;
const authFunctions: AuthFunctions = internal.auth;

// Create client with Convex adapter and triggers
export const authClient = createClient<DataModel, typeof schema>({
  authFunctions,
  schema,
  internalMutation, // Optional: custom mutation wrapper (see below)
  triggers: {
    user: {
      beforeCreate: async (_ctx, data) => {
        // Ensure every user has a username
        const username =
          data.username?.trim() ||
          data.email?.split('@')[0] ||
          `user-${Date.now()}`;

        return { ...data, username };
      },
      // ctx.db version - for ctx.table, see Triggers documentation
      onCreate: async (ctx, user) => {
        // Create related records after signup
        await ctx.db.insert('profiles', {
          userId: user._id,
          bio: '',
        });
      },
    },
  },
});

// Auth options factory
export const createAuthOptions = (ctx: GenericCtx) =>
  ({
    baseURL: process.env.SITE_URL!,
    database: authClient.httpAdapter(ctx),
    plugins: [
      convex({
        authConfig,
        jwks: process.env.JWKS,
      }),
      admin(),
    ],
    session: {
      expiresIn: 60 * 60 * 24 * 30, // 30 days
      updateAge: 60 * 60 * 24 * 15, // 15 days
    },
    socialProviders: {
      google: {
        clientId: process.env.GOOGLE_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      },
    },
    // Fallback for CLI schema generation
    trustedOrigins: [process.env.SITE_URL ?? 'http://localhost:3000'],
  }) satisfies BetterAuthOptions;

// Create auth instance for HTTP routes
export const createAuth = (ctx: GenericCtx) => betterAuth(createAuthOptions(ctx));

// IMPORTANT: Use getAuth for queries/mutations (direct DB access)
export const getAuth = <Ctx extends QueryCtx | MutationCtx>(ctx: Ctx) => {
  return betterAuth({
    ...createAuthOptions(ctx),
    database: authClient.adapter(ctx, createAuthOptions),
  });
};

// Export trigger handlers for Convex
export const {
  beforeCreate,
  beforeDelete,
  beforeUpdate,
  onCreate,
  onDelete,
  onUpdate,
} = authClient.triggersApi();

// Export CRUD functions for Better Auth
export const {
  create,
  deleteMany,
  deleteOne,
  findMany,
  findOne,
  updateMany,
  updateOne,
  getLatestJwks,
  rotateKeys,
} = createApi(schema, createAuth, {
  internalMutation, // Optional: same wrapper as createClient
  skipValidation: true, // Smaller generated types
});

// Export auth instance for Better Auth CLI
// biome-ignore lint/suspicious/noExplicitAny: Required for CLI
export const auth = betterAuth(createAuthOptions({} as any));

// Override with custom indexes
user: authSchema.user.index('username', ['username']),

// polyfill MessageChannel without using node:events
if (typeof MessageChannel === 'undefined') {
  class MockMessagePort {
    onmessage: ((ev: MessageEvent) => void) | undefined;
    onmessageerror: ((ev: MessageEvent) => void) | undefined;

    addEventListener() {}
    close() {}

    dispatchEvent(_event: Event): boolean {
      return false;
    }

    postMessage(_message: unknown, _transfer: Transferable[] = []) {}
    removeEventListener() {}
    start() {}
  }

  class MockMessageChannel {
    port1: MockMessagePort;
    port2: MockMessagePort;

    constructor() {
      this.port1 = new MockMessagePort();
      this.port2 = new MockMessagePort();
    }
  }

  globalThis.MessageChannel =
    MockMessageChannel as unknown as typeof MessageChannel;
}

SITE_URL=http://localhost:3000
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

npx better-convex env sync --auth

npx convex run auth:rotateKeys | npx convex env set JWKS

// ✅ In queries/mutations: Use getAuth (direct DB access)
export const someQuery = publicQuery
  .query(async ({ ctx }) => {
    const auth = getAuth(ctx);
    const session = await auth.api.getSession({ headers: await getHeaders(ctx) });
  });

// ✅ In HTTP routes/actions: Use createAuth (HTTP adapter)
export const someAction = publicAction
  .action(async ({ ctx }) => {
    const auth = createAuth(ctx);
    // Use for webhooks, external API calls
  });

import { internalMutationWithTriggers } from './lib/triggers';

export const authClient = createClient({
  // ...
  internalMutation: internalMutationWithTriggers,
});

export const { ... } = createApi(schema, createAuth, {
  internalMutation: internalMutationWithTriggers,
});

npx convex deploy --prod

npx convex run auth:getLatestJwks --prod | npx convex env set JWKS --prod

npx convex run auth:rotateKeys --prod | npx convex env set JWKS --prod

convex({
  authConfig,
})

definePayload: ({ user, session }) => ({
  ...omit(user, ["id", "image"]),
  sessionId: session.id,
  iat: Math.floor(new Date().getTime() / 1000),
});

convex({
  authConfig,
  jwt: {
    expirationSeconds: 60 * 60 * 4, // 4 hours
    definePayload: ({ user, session }) => ({
      name: user.name,
      email: user.email,
      role: user.role,
      sessionId: session.id,
    }),
  },
})

convex({
  authConfig,
  jwks: process.env.JWKS,
})

convex({
  authConfig,
  options: {
    basePath: "/custom/auth/path",
  },
})

import { getAuthUserIdentity } from 'better-convex/auth';

const identity = await getAuthUserIdentity(ctx);

if (identity) {
  identity.userId;    // Id<'user'>
  identity.sessionId; // Id<'session'>
  identity.subject;   // string (user ID as string)
}

import { getSession } from 'better-convex/auth';

const session = await getSession(ctx);

if (session) {
  session._id;                  // Id<'session'>
  session.userId;               // Id<'user'>
  session.activeOrganizationId; // Id<'organization'> | null
  session.expiresAt;            // number
}

import { getHeaders } from 'better-convex/auth';

const headers = await getHeaders(ctx);
// Headers { authorization: 'Bearer ...', x-forwarded-for: '...' }

// Use with fetch
const response = await fetch('https://api.example.com', {
  headers,
});