Getting Started

Client Setup

Configure the client-side authentication client.

Prompt

Set up the client auth config for @onmax/nuxt-better-auth.

- Create `app/auth.config.ts` with a default export using `defineClientAuth` from `@onmax/nuxt-better-auth/config`
- Object syntax: `defineClientAuth({})` or function syntax: `defineClientAuth(({ siteUrl }) => ({}))`
- Add client plugin equivalents for every server plugin (e.g. `adminClient()` from `better-auth/client/plugins`)
- The module calls the factory with the correct `baseURL` at runtime
- `useUserSession()` is auto-imported and provides `user`, `session`, `loggedIn`, `ready`, `signOut`
- `useSignIn()`, `useSignUp()`, and `useAuthClient()` are auto-imported for auth actions and direct client access

Use this page when the server config exists and you want to wire the Better Auth client into your Nuxt app.

Create the Client Config

Create app/auth.config.ts with a default export using defineClientAuth.

The defineClientAuth helper supports two syntaxes: an object for simple configurations, or a function when you need access to context like the resolved site URL.

app/auth.config.ts

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

// Object syntax (simplest)
export default defineClientAuth({})

// Function syntax (access context)
export default defineClientAuth(({ siteUrl }) => ({
  // siteUrl contains the resolved base URL
}))

The helper creates a factory function that the module calls with the correct baseURL at runtime.

Using Plugins

If you added a plugin in your server config (server/auth.config.ts), make sure to add its client equivalent here.

app/auth.config.ts

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

export default defineClientAuth({
  plugins: [
    adminClient() // Must match the server plugin
  ]
})

Common Plugin Combinations

Admin + Two Factor

app/auth.config.ts

import { defineClientAuth } from '@onmax/nuxt-better-auth/config'
import { adminClient, twoFactorClient } from 'better-auth/client/plugins'

export default defineClientAuth({
  plugins: [adminClient(), twoFactorClient()]
})

Use the client in your app

useUserSession() is auto-imported in pages and components.

pages/login.vue

<script setup lang="ts">
definePageMeta({ auth: 'guest' })

const signInEmail = useSignIn('email')

async function login(email: string, password: string) {
  await signInEmail.execute(
    { email, password },
    { onSuccess: () => navigateTo('/app') },
  )
}
</script>

Verify the result

Confirm all of the following:

useUserSession() is available without a manual import
useAuthClient() returns the Better Auth client on the browser after hydration
client plugins are registered on both server and client when required by Better Auth
sign-in and sign-out update user, session, and loggedIn