nuxt-x-auth-better

Better Auth frontend layer for Nuxt 4. Provides 19 auto-imported XAuth-prefixed components, useXAuth and useOrganization composables, global auth and organization middleware, 18 pre-built pages, and a fully typed app.config.ts interface — all built on Nuxt UI v4. Pairs with @xenterprises/fastify-x-auth-better on the backend.

What the consumer writes

The layer ships batteries included: all auth pages, routes, layouts, middleware, and components come from the layer. A minimal consumer is an extends entry, one environment variable, and an optional app/app.config.ts for branding and feature flags.

npm install @xenterprises/nuxt-x-auth-better better-auth

better-auth (^1.0.0, verified on the 1.6.x line) and nuxt (^4.0.0) are peer dependencies — install them in the consuming app.

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@xenterprises/nuxt-x-auth-better'],
})

# .env — required: the base URL of the Better Auth backend
NUXT_PUBLIC_X_AUTH_BASE_URL=https://api.example.com

// app/app.config.ts — must live in app/, not the project root
export default defineAppConfig({
  xAuth: {
    features: {
      oauth: true,
      organization: true,
    },
    oauthProviders: [
      { id: 'google', label: 'Google', icon: 'i-simple-icons-google' },
      { id: 'github', label: 'GitHub', icon: 'i-simple-icons-github' },
    ],
    ui: {
      brandName: 'Acme',
      tagline: 'Sign in to your account',
    },
  },
})

That is the whole consumer surface: /auth/login, /auth/signup, /auth/forgot-password, and the rest of the 18 pages work immediately against the backend, with route protection enforced by the global middleware.

Installation

npm install @xenterprises/nuxt-x-auth-better better-auth

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@xenterprises/nuxt-x-auth-better'],
})

The layer declares the public.x.auth runtime config schema itself, so the environment variable NUXT_PUBLIC_X_AUTH_BASE_URL is picked up automatically. To wire a differently-named variable, override the runtime config in the consumer's nuxt.config.ts:

export default defineNuxtConfig({
  extends: ['@xenterprises/nuxt-x-auth-better'],
  runtimeConfig: {
    public: {
      x: {
        auth: {
          baseUrl: process.env.MY_AUTH_API_URL || '',
          authPath: '/auth',
        },
      },
    },
  },
})

Override defaults in app/app.config.ts (every key shown with its layer default):

// app/app.config.ts
export default defineAppConfig({
  xAuth: {
    redirects: {
      login: '/auth/login',
      signup: '/auth/signup',
      afterLogin: '/',
      afterSignup: '/',
      afterLogout: '/auth/login',
      forgotPassword: '/auth/forgot-password',
    },
    features: {
      oauth: false,
      magicLink: false,
      otp: false,
      forgotPassword: true,
      signup: true,
      organization: false,
      teams: false,
    },
    publicRoutes: [],
    plugins: {
      admin: false,
      stripe: false,
    },
    oauthProviders: [],
    ui: {
      showLogo: true,
      showBrandName: true,
      brandName: '',
      tagline: '',
      layout: 'centered',
    },
  },
})

What the Layer Provides

Components (auto-imported, XAuth prefix):

• XAuthLogin — Email/password login form with optional magic link and OAuth
• XAuthSignup — Registration form with name, email, and password
• XAuthForgotPassword — Password reset request form
• XAuthMagicLink — Magic link email input form
• XAuthOAuthButton — Single OAuth provider button (Google, GitHub, etc.)
• XAuthOAuthButtonGroup — Multiple OAuth provider buttons from app.config.ts
• XAuthHandler — Callback handler for OAuth and magic link redirects
• XAuthResendVerification — Resend email verification form (non-disclosing)
• XAuthActiveSessions — List and revoke the current user's sessions/devices
• XAuthOrganizationSwitcher — List and navigate between organizations
• XAuthOrganizationCreate — Create a new organization
• XAuthOrganizationSettings — Edit or delete organization
• XAuthOrganizationMembers — Manage members and roles
• XAuthOrganizationInvite — Invite a new member
• XAuthOrganizationInvitations — List pending invitations
• XAuthTeamList — List teams in an organization
• XAuthTeamCreate — Create a team
• XAuthTeamSettings — Edit or delete team
• XAuthTeamMembers — Manage team members

Composables:

• useXAuth() — Full Better Auth client wrapper with session state, auth methods, and user management
• useOrganization() — Organizations & Teams state, CRUD, members, invitations, teams, and access control

Pages:

• /auth/login — Login page
• /auth/signup — Signup page
• /auth/forgot-password — Forgot password page
• /auth/magic-link — Magic link request page
• /auth/reset-password — Reset password page (token from email link)
• /auth/handler/[...slug] — OAuth callback and magic link verification handler
• /auth/logout — Logout action page
• /org — Organization list / switcher
• /org/create — Create a new organization
• /org/:slug — Organization dashboard
• /org/:slug/settings — Organization settings
• /org/:slug/members — Member list
• /org/:slug/invite — Invite member
• /org/:slug/invitations — Pending invitations
• /org/:slug/teams — Team list
• /org/:slug/teams/create — Create team
• /org/:slug/teams/:teamId — Team settings + members
• /auth/handler/invitation?id=... — Public invitation accept handler

Middleware:

• auth.global — Global route guard; redirects unauthenticated users to login and authenticated users away from guest-only routes
• organization.global — Protects organization routes, resolves org by slug, enforces membership and role rules

App Config Options

Configure under the xAuth key in app/app.config.ts:

Runtime Config

The full auth URL is constructed as baseUrl + authPath (e.g. https://api.example.com/auth).

useXAuth() Composable

const {
  user,               // ComputedRef<AuthUser | null>
  isAuthenticated,    // ComputedRef<boolean>
  isLoading,          // ComputedRef<boolean>
  emailSent,          // Ref<boolean>
  codeSent,           // Ref<boolean>
  needsEmailVerification, // Ref<boolean> — true when login fails with EMAIL_NOT_VERIFIED
  session,            // ComputedRef<Session | null>
  sessionError,       // ComputedRef<Error | null>
  config,             // ComputedRef<AuthConfig>
  authClient,         // Better Auth client instance

  login,              // (email, password) => Promise<AuthUser | null>
  signup,             // (email, password, name?) => Promise<AuthUser | null>
  logout,             // () => Promise<boolean>
  forgotPassword,     // (email) => Promise<boolean>
  resetPassword,      // (token, newPassword) => Promise<true | { error }>
  loginWithProvider,  // (providerName) => Promise<boolean>
  sendMagicLink,      // (email, options?) => Promise<boolean>
  getCurrentUser,     // () => Promise<AuthUser | null>
  getToken,           // () => Promise<string | null>
  getAuthHeaders,     // () => Promise<{ Authorization: string }>
  handleMagicLinkCallback, // (token) => Promise<true | { error }>
  verifyEmail,        // (token) => Promise<true | { error }>
  resendVerificationEmail, // (email) => Promise<boolean> — non-disclosing
  listSessions,       // () => Promise<AuthSession[]>
  revokeSession,      // (token) => Promise<boolean>
  changePassword,     // (currentPassword, newPassword) => Promise<true | { error }>
  updateUser,         // ({ name?, image? }) => Promise<true | { error }>
  deleteAccount,      // () => Promise<boolean>
  resetState,         // () => void
} = useXAuth()

Minimal Usage Example

<script setup>
const { user, isAuthenticated, logout } = useXAuth()
</script>

<template>
  <div v-if="isAuthenticated">
    Welcome, {{ user?.name }}
    <UButton @click="logout">Sign Out</UButton>
  </div>
  <XAuthLogin v-else />
</template>

OAuth Providers Example

// app/app.config.ts
export default defineAppConfig({
  xAuth: {
    features: { oauth: true },
    oauthProviders: [
      { id: 'google', label: 'Google', icon: 'i-simple-icons-google' },
      { id: 'github', label: 'GitHub', icon: 'i-simple-icons-github' },
    ],
  },
})

<XAuthOAuthButtonGroup />

Global Middleware Behavior

The auth.global middleware runs on every route navigation:

Extra public routes (beyond the built-in /auth/handler and /auth/logout) can be registered via xAuth.publicRoutes in app/app.config.ts.

Organizations & Teams

Enable features.organization: true in app.config.ts and add the Better Auth organization plugin on your server to activate the full Organizations & Teams implementation. See the dedicated guides for details:

• Organizations & Teams — enabling, components, pages, middleware, and server setup
• useOrganization — full composable API reference

Layer Architecture

Environment Variables

Breaking changes

2026-07 (next minor): the vestigial xAuth.tokens app-config block and the dead useCookieStorage util (app/utils/cookieStorage.ts) were removed — Better Auth manages its own cookies. Consumers referencing either must drop the usage.