Composables

useXAuth

Stack Auth client wrapper composable with SSR-safe useState shared state and OAuth/magic-link/OTP/password-reset support.

useXAuth

Stack Auth frontend composable for the nuxt-x-auth-stack layer. Wraps the Stack Auth client singleton with SSR-safe shared state via Nuxt's useState — all composable instances on the same page share the same user, isLoading, emailSent, and codeSent refs. Supports email/password, OAuth, magic links, OTP, and email verification out of the box. The layer is client-side only (ssr: false).

Usage

const {
  user,
  isAuthenticated,
  isLoading,
  emailSent,
  codeSent,
  config,

  login,
  signup,
  logout,
  loginWithProvider,

  forgotPassword,
  resetPassword,
  verifyPasswordResetCode,

  sendMagicLink,
  signInWithMagicLink,

  sendOtp,
  verifyOtp,

  verifyEmail,

  getCurrentUser,
  getToken,
  getAuthHeaders,

  resetState,
  getClient,
} = useXAuth()

Returns

State

Key	Type	Description
`user`	`Ref<XAuthUser \| null>`	The currently authenticated user. Shared via `useState` across all instances.
`isAuthenticated`	`ComputedRef<boolean>`	`true` when `user` is not `null`.
`isLoading`	`Ref<boolean>`	`true` while any auth operation is in progress. Shared via `useState`.
`emailSent`	`Ref<boolean>`	`true` after `forgotPassword` or `sendMagicLink` succeeds.
`codeSent`	`Ref<boolean>`	`true` after `sendOtp` succeeds.
`config`	`ComputedRef<XAuthConfig>`	Reactive reference to the full `xAuth` app config from `app.config.ts`.

Auth Methods

Key	Type	Description
`login`	`(email: string, password: string) => Promise<XAuthUser \| null>`	Signs in with email and password. Returns the user on success.
`signup`	`(email: string, password: string) => Promise<XAuthUser \| null>`	Creates a new Stack Auth account. Returns the user on success.
`logout`	`() => Promise<boolean>`	Signs out and redirects to `redirects.afterLogout`.
`loginWithProvider`	`(providerName: string) => Promise<boolean>`	Initiates an OAuth flow with the named provider (e.g. `'google'`, `'github'`).

Password

Key	Type	Description
`forgotPassword`	`(email: string) => Promise<boolean>`	Sends a password reset email. Sets `emailSent` to `true` on success.
`resetPassword`	`(code: string, newPassword: string) => Promise<{ success: true } \| { error: string }>`	Applies a new password using the reset code.
`verifyPasswordResetCode`	`(code: string) => Promise<result>`	Validates a password reset code before showing the new password form.

Magic Link

Key	Type	Description
`sendMagicLink`	`(email: string) => Promise<boolean>`	Sends a magic link email. Sets `emailSent` to `true` on success.
`signInWithMagicLink`	`(code: string) => Promise<{ success: true } \| { error: string }>`	Completes the magic link sign-in from the callback URL.

OTP

Key	Type	Description
`sendOtp`	`(email: string) => Promise<string \| null>`	Sends an OTP code to the email. Returns a nonce required for verification. Sets `codeSent` to `true`.
`verifyOtp`	`(code: string, nonce: string) => Promise<XAuthUser \| null>`	Verifies the OTP code using the nonce returned by `sendOtp`. Signs the user in on success.

Email Verification

Key	Type	Description
`verifyEmail`	`(code: string) => Promise<{ success: true } \| { error: string }>`	Verifies the user's email address using the code from the verification link.

Utilities

Key	Type	Description
`getCurrentUser`	`() => Promise<XAuthUser \| null>`	Re-fetches the current user from Stack Auth and updates reactive state.
`getToken`	`() => Promise<string \| null>`	Returns the current access token from the Stack Auth session.
`getAuthHeaders`	`() => Promise<{ Authorization: string }>`	Returns `{ Authorization: 'Bearer <token>' }` for use in API calls.
`resetState`	`() => void`	Resets `emailSent` and `codeSent` to `false`.
`getClient`	`() => StackClientApp`	Returns the underlying Stack Auth client singleton for direct SDK access.

`XAuthUser` Type

interface XAuthUser {
  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>

// OTP flow — nonce must be passed to verifyOtp
const nonce = await sendOtp('user@example.com')
// user enters 6-digit code
const user = await verifyOtp('123456', nonce!)

// Magic link flow
await sendMagicLink('user@example.com')
// user clicks link → /auth/handler/magic-link-callback
// that page calls:
await signInWithMagicLink(route.query.code as string)

// OAuth
await loginWithProvider('google')

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

// Direct Stack SDK access
const client = getClient()

AI Context

composable: useXAuth
package: "@xenterprises/nuxt-x-auth-stack"
use-when: >
  All authentication operations in a Nuxt app using Stack Auth as the backend.
  Covers email/password, OAuth, magic links, OTP, email verification, and
  password reset. State is SSR-safe via useState. For OTP, store the nonce
  returned by sendOtp and pass it to verifyOtp. For direct Stack SDK access,
  use getClient(). Requires NUXT_PUBLIC_STACK_PROJECT_ID and
  NUXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY environment variables.
  The layer is client-side only (ssr: false).

Edit this pageorReport an issue

Handler

Catch-all auth callback handler for Stack Auth — OAuth redirects, magic link, email verification, and password reset.

Configuration

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