How It Works

What you provide

• server/auth.config.ts exports defineServerAuth(...)
• app/auth.client.ts exports createAppAuthClient(baseURL)

The module validates both files exist at build time.

What the module adds

Server

• serverAuth() creates and caches a Better Auth instance by calling your config and injecting:
  • NuxtHub database via the Drizzle adapter
  • runtimeConfig.betterAuthSecret
  • runtimeConfig.public.siteUrl as baseURL
• A catch-all API handler at /api/auth/** that forwards to Better Auth.
• Nitro middleware for /api/** that enforces routeRules.role using requireUserSession(...).

Client

• useUserSession() (auto-imported) creates a Better Auth client and manages user/session state.
• A global route middleware that reads definePageMeta({ auth, role }) to redirect/deny access.
• <BetterAuthState> to render once useUserSession().ready is true.

Route protection layers

• Pages: driven by meta.auth / meta.role (can be set per-page or synced from routeRules).
• API routes: only routeRules.role is enforced by default.

See also:

• /core-concepts/route-protection
• /guides/protecting-api-routes