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. Point the Client to the External Server

defineClientAuth is wrapped by the module at runtime, so baseURL here is overridden. To target an external auth server, set the site URL:

.env

NUXT_PUBLIC_SITE_URL="https://auth.example.com"

This value becomes the Better Auth client base URL in client-only mode.

3. Set Redirect Paths (Optional)

Control where users are sent after auth checks:

nuxt.config.ts

export default defineNuxtConfig({
  auth: {
    redirects: {
      login: '/login',
      guest: '/',
    },
  },
})

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

In client-only mode, NUXT_PUBLIC_SITE_URL is used as the auth client base URL. Use auth.redirects in nuxt.config.ts to control frontend navigation paths.

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>
    <template #default="{ user }">
      <div v-if="user">Welcome, {{ user.name }}</div>
      <div v-else>Please log in</div>
    </template>
    <template #placeholder>
      <div>Loading...</div>
    </template>
  </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