Guides

External Auth Backend

Use nuxt-better-auth with a separate Better Auth server.

When your Better Auth server runs on a separate backend (e.g., standalone h3/Nitro project, Express, or any other server), use clientOnly mode.

When to Use

Microservices architecture: Auth service is a separate deployment
Shared auth: Multiple frontends share one auth backend
Existing backend: You already have a Better Auth server running elsewhere

Configuration

1. Enable Client-Only Mode

nuxt.config.ts

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

2. Configure Client to Point to External Server

app/auth.config.ts

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

export default defineClientAuth({
  baseURL: 'https://auth.example.com', // Your external auth server
})

3. Set Site URL (Optional)

Auto-detected on Vercel/Cloudflare/Netlify. For other platforms:

.env

NUXT_PUBLIC_SITE_URL="https://your-frontend.com"

What Changes in Client-Only Mode

Feature	Full Mode	Client-Only
`server/auth.config.ts`	Required	Not needed
`/api/auth/**` handlers	Auto-registered	Skipped
`NUXT_BETTER_AUTH_SECRET`	Required	Not needed
Server middleware	Enabled	Skipped
Schema generation	Enabled	Skipped
Devtools	Enabled	Skipped
SSR session hydration	Server-side	Client-side only
`useUserSession()`	Works	Works
Route protection	Works	Works (client-side)
`<BetterAuthState>`	Works	Works

Important Notes

In client-only mode, all auth requests go directly to your external server. Ensure:

CORS is configured on your auth server to allow requests from your frontend (with credentials: true)
Cookies use SameSite=None; Secure for cross-origin requests (HTTPS required)
Your auth server's trustedOrigins includes your frontend URL

NUXT_PUBLIC_SITE_URL should be your frontend URL (for redirects). The auth server URL is configured via baseURL in app/auth.config.ts.

Server utilities like serverAuth(), getUserSession() and requireUserSession() are not available in client-only mode since there's no local auth server.

SSR Considerations

In client-only mode, session data is fetched client-side only. This means:

Server-rendered pages won't have access to session data during SSR
Pages will initially render as "unauthenticated" and hydrate with session data on the client
Use <BetterAuthState> component to handle loading states gracefully

<template>
  <BetterAuthState v-slot="{ isLoading, user }">
    <div v-if="isLoading">Loading...</div>
    <div v-else-if="user">Welcome, {{ user.name }}</div>
    <div v-else>Please log in</div>
  </BetterAuthState>
</template>

If you need SSR session hydration, consider using full mode with a local auth server instead.

Example Architecture

┌─────────────────┐     ┌─────────────────┐
│   Nuxt App      │────▶│  Auth Server    │
│  (clientOnly)   │     │ (Better Auth)   │
│                 │◀────│                 │
└─────────────────┘     └────────┬────────┘
                                 │
                        ┌────────▼────────┐
                        │    Database     │
                        └─────────────────┘

Configuration - Module options reference
Database-Less Mode - JWE sessions without database