Composables

useXAuth

Better Auth client wrapper composable — session state, auth methods, and user management for nuxt-x-auth-better.

useXAuth

Better Auth frontend composable for the nuxt-x-auth-better layer. Wraps the Better Auth client with reactive session state, a full set of auth methods, and computed helpers. The auth URL is constructed from runtimeConfig.public.x.auth.baseUrl + authPath. All UI components in this layer consume useXAuth internally.

Usage

const {
  user,
  isAuthenticated,
  isLoading,
  emailSent,
  session,
  sessionError,
  config,
  authClient,

  login,
  signup,
  logout,
  forgotPassword,
  resetPassword,
  loginWithProvider,
  sendMagicLink,
  getCurrentUser,
  getToken,
  getAuthHeaders,
  handleMagicLinkCallback,
  changePassword,
  updateUser,
  deleteAccount,
  resetState,
} = useXAuth()

Returns

State

Key	Type	Description
`user`	`ComputedRef<AuthUser \| null>`	The currently authenticated user derived from the active session. `null` when signed out.
`isAuthenticated`	`ComputedRef<boolean>`	`true` when `user` is not `null`.
`isLoading`	`ComputedRef<boolean>`	`true` while the session is being fetched or an auth operation is in progress.
`emailSent`	`Ref<boolean>`	`true` after `forgotPassword` or `sendMagicLink` completes successfully.
`session`	`ComputedRef<Session \| null>`	The raw Better Auth session object.
`sessionError`	`ComputedRef<Error \| null>`	Any error returned when fetching the session.
`config`	`ComputedRef<AuthConfig>`	Reactive reference to the full `xAuth` app config from `app.config.ts`.
`authClient`	`BetterAuthClient`	The underlying Better Auth client instance for direct SDK access.

Auth Methods

Key	Type	Description
`login`	`(email: string, password: string) => Promise<AuthUser \| null>`	Signs in with email and password. Returns the user on success.
`signup`	`(email: string, password: string, name?: string) => Promise<AuthUser \| null>`	Creates a new account. The optional `name` is passed to Better Auth on registration.
`logout`	`() => Promise<boolean>`	Signs out and redirects to `redirects.afterLogout`.
`forgotPassword`	`(email: string) => Promise<boolean>`	Requests a password reset email. Sets `emailSent` to `true` on success.
`resetPassword`	`(token: string, newPassword: string) => Promise<true \| { error: string }>`	Applies a new password using the reset token from the email link.
`loginWithProvider`	`(providerName: string) => Promise<boolean>`	Initiates an OAuth flow with the named provider (e.g. `'google'`, `'github'`).
`sendMagicLink`	`(email: string, options?: object) => Promise<boolean>`	Sends a magic link email. Sets `emailSent` to `true` on success.
`handleMagicLinkCallback`	`(token: string) => Promise<true \| { error: string }>`	Completes the magic link sign-in from the callback URL.

User Management

Key	Type	Description
`getCurrentUser`	`() => Promise<AuthUser \| null>`	Re-fetches the current user and updates reactive state.
`changePassword`	`(currentPassword: string, newPassword: string) => Promise<true \| { error: string }>`	Changes the authenticated user's password.
`updateUser`	`(data: { name?: string; image?: string }) => Promise<true \| { error: string }>`	Updates the user's profile fields.
`deleteAccount`	`() => Promise<boolean>`	Permanently deletes the current user's account.

Utilities

Key	Type	Description
`getToken`	`() => Promise<string \| null>`	Returns the current access token from the Better Auth session.
`getAuthHeaders`	`() => Promise<{ Authorization: string }>`	Returns `{ Authorization: 'Bearer <token>' }` for use in API calls.
`resetState`	`() => void`	Resets `emailSent` to `false`.

`AuthUser` Shape

{
  id: string
  email: string
  name: string
  avatar?: string
  emailVerified: boolean
  metadata?: Record<string, any>
}

Examples

<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>

// Change password
const result = await changePassword('oldPass', 'newPass')
if (result !== true) console.error(result.error)

// Update profile
await updateUser({ name: 'Jane Doe', image: 'https://example.com/avatar.jpg' })

// Authenticated API call
const headers = await getAuthHeaders()
// { Authorization: 'Bearer eyJ...' }

// Direct SDK access
const client = authClient

AI Context

composable: useXAuth
package: "@xenterprises/nuxt-x-auth-better"
use-when: >
  All authentication and user management operations in a Nuxt app using the
  nuxt-x-auth-better layer (Better Auth backend). Provides session state,
  login/signup/logout, OAuth, magic links, password management, and profile
  updates. The authClient property exposes the raw Better Auth client for
  advanced SDK usage. Pairs with fastify-x-auth-better on the server side.
  Configure baseUrl via NUXT_PUBLIC_AUTH_BASE_URL.

Edit this pageorReport an issue

Handler

Catch-all auth callback handler for OAuth redirects and magic link completions with Better Auth.

Configuration

app.config.ts and runtimeConfig reference for @xenterprises/nuxt-x-auth-better.