Convex

Convex provides a real-time backend with automatic data synchronization. You can combine it with Better Auth to build applications where authenticated users access their own data with live updates.

Setup

The nuxt-convex module connects your Nuxt application to Convex. Better Auth handles authentication while Convex manages your application data.

npx nuxt module add nuxt-convex

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

Authenticated Queries

Better Auth provides the authenticated user through the useUserSession composable. You can pass the user ID to Convex queries to fetch user-specific data with real-time updates.

<script setup lang="ts">
import { api } from '#convex/api'

const { user } = useUserSession()
const { data: tasks } = useConvexQuery(
  api.tasks.list,
  computed(() => user.value ? { userId: user.value.id } : undefined),
  { ssr: false }
)
</script>

The computed wrapper ensures the query re-subscribes automatically when the user changes. When you pass undefined as the arguments, Convex pauses the query and returns no data. This behavior prevents unauthorized queries when the user is not authenticated.

Convex as Auth Database

Better Auth typically stores authentication data in a SQL database. The @convex-dev/better-auth adapter lets you store users, sessions, and accounts directly in Convex instead. This approach keeps all your data in one place with Convex's real-time synchronization.

Install the adapter

The adapter requires exact versions to ensure compatibility between Better Auth and Convex.

pnpm add @convex-dev/better-auth better-auth --save-exact

Configure the Convex component

The Better Auth component registers the authentication tables in your Convex database.

import betterAuth from '@convex-dev/better-auth/convex.config'
import { defineApp } from 'convex/server'

const app = defineApp()
app.use(betterAuth)
export default app

Connect Better Auth to Convex

The adapter replaces the standard database configuration in your auth config. The convex() plugin handles session management and token refresh through Convex.

import { components } from '#convex/api'
import { createClient } from '@convex-dev/better-auth'
import { convex } from '@convex-dev/better-auth/server/plugins'
import { defineServerAuth } from '@onmax/nuxt-better-auth/config'

const authComponent = createClient(components.betterAuth)

export default defineServerAuth({
  database: authComponent.adapter(),
  plugins: [convex()],
  emailAndPassword: { enabled: true },
})