Better Auth

Use this guide when your Nuxt app needs Better Auth on the server and Convex should act as the database layer.

Before you begin

This integration is Nuxt-only. The supported baseline in this repo is the email/password flow exercised by the playground.

Treat this integration as dependency-constrained. The versions below are a tested set, not a promise that every nearby version combination works.

GitHub auth and other social providers can exist, but they stay optional and secondary compared with the supported email/password path.

Install the tested stack

pnpm add @onmax/nuxt-better-auth@0.0.2-alpha.31 \
  @convex-dev/better-auth@0.11.3 \
  better-auth@1.5.6

Configure Nuxt

export default defineNuxtConfig({
  modules: ['nuxt-convex', '@onmax/nuxt-better-auth'],
  auth: {
    database: {
      provider: 'convex',
    },
  },
})

nuxt-convex registers the convex provider on the Better Auth database hook and exports createConvexHttpAdapter from nuxt-convex/better-auth.

Add the required environment

CONVEX_URL=https://your-project.convex.cloud
BETTER_AUTH_SECRET=replace-with-a-secret-at-least-32-characters

Add optional provider-specific secrets later if you expand beyond the email/password baseline.

Enable email and password in Convex

emailAndPassword: {
  enabled: true,
  requireEmailVerification: false,
},

Add the Nuxt auth config files

import { defineServerAuth } from '@onmax/nuxt-better-auth/config'

export default defineServerAuth(() => ({
  appName: 'nuxt-convex app',
}))

import { convexClient } from '@convex-dev/better-auth/client/plugins'
import { defineClientAuth } from '@onmax/nuxt-better-auth/config'

export default defineClientAuth(({ siteUrl }) => ({
  baseURL: new URL('/api/auth', siteUrl).toString(),
  plugins: [convexClient()],
}))

Verify the result

The integration is working when:

• Better Auth resolves the convex database provider
• email/password sign-in succeeds
• the authenticated session is visible in the Nuxt app

Use the Session & Diagnostics area in the playground as the validation reference for the supported flow.

Next steps

• Read R2 if your app also needs bucket uploads
• Read Module configuration if you need to override the resolved Convex URL