Better Auth Plugins

Additional Better Auth plugins have two sides:

server configuration inside createAuth;
client plugin methods exposed through useConvexAuth().client.

Some plugins also change the Better Auth component schema.

Define client plugins

Create one convex-auth.ts at the Nuxt srcDir:

convex-auth.ts

import { organizationClient } from 'better-auth/client/plugins'
import { defineConvexAuthClient } from '@lupinum/better-convex-nuxt/auth-client'

export default defineConvexAuthClient({
  plugins: [organizationClient()],
})

The module discovers this file, prepends the required Convex client plugin, instantiates one client, and generates type registration.

The definition itself is frozen metadata. It never creates a client.

Configure the server plugin

convex/auth.ts

import { convexAuth } from '@lupinum/better-convex-nuxt/convex-auth'

import { createLocalAuthPlugins } from './betterAuth/schema-plugins'

return betterAuth({
  database: authComponent.adapter(ctx),
  plugins: [
    ...createLocalAuthPlugins(`${siteUrl}/api/auth`),
    convexAuth({
      authConfig,
      sessionJwt: {
        audience: 'convex',
        expirationTime: '15m',
        issuer: convexSiteUrl,
      },
    }),
  ],
})

Server and client plugin configuration must agree.

Call a typed plugin method

const { client } = useConvexAuth()

const organizations = await client?.organization.list()

Call session-changing operations through this integrated client; every Promise-returning client operation crosses Convex identity coordination before it settles.

Schema-changing plugins

Admin, organization, API-key, and similar plugins can add tables or fields. The safe path is:

Define convex/betterAuth/schema-plugins.ts as the one schema-changing plugin list used by generation and runtime.
Default-export environment-independent build options from convex/betterAuth/schema-options.ts.

Generate both artifacts together:

bash

pnpm exec better-convex-nuxt-auth-schema \
  --config convex/betterAuth/schema-options.ts \
  --output convex/betterAuth

Define the local component functions with defineAuthAdapterFunctions({ schema, metadata }).
Register that one local component as betterAuth in convex/convex.config.ts.
Create the component client with the generated local API and typecheck server/client plugin calls.

Run the command with --check in CI. The pair carries one deterministic fingerprint, and the adapter refuses a mismatch. Schema generation clears production auth secrets and uses only the explicit build-only options.

Use the repository's starters/team/convex/betterAuth and auth-security fixtures as the current reference shape.

Do not mount the packaged component beside the local one, copy the adapter, or maintain two plugin lists. Do not assume an arbitrary Better Auth plugin works because its client method typechecks. Verify schema, routes, runtime behavior, and security constraints for the pinned versions.