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`, `signIn`, `signUp`, `signOut`

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 { signIn } = useUserSession()

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

Verify the result

Confirm all of the following:

useUserSession() is available without a manual import
client is available 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