npm install @xenterprises/nuxt-x-auth

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

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

// app/app.config.ts — must live in app/, not the project root
export default defineAppConfig({
  xAuth: {
    provider: 'stack', // 'stack' | 'better-auth' | 'neon-auth' | 'local'
    // Everything else has working defaults — override only what you need:
    redirects: { afterLogin: '/dashboard' },
    features: { oauth: true },
    oauthProviders: [
      { id: 'google', label: 'Google', icon: 'i-logos-google-icon' },
    ],
    ui: { brandName: 'My App' },
  },
})

# .env — only the vars for the provider you selected (Stack Auth shown)
NUXT_PUBLIC_STACK_PROJECT_ID=...
NUXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=...

// app/app.config.ts
export default defineAppConfig({
  xAuth: {
    provider: 'stack', // 'stack' | 'better-auth' | 'neon-auth' | 'local'

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

    oauthProviders: [
      { id: 'google', label: 'Google', icon: 'i-logos-google-icon' },
      { id: 'github', label: 'GitHub', icon: 'i-logos-github-icon' },
    ],

    tokens: {
      accessCookie: 'x_auth_access',
      refreshCookie: 'x_auth_refresh',
      hasRefresh: true,
    },

    ui: {
      showLogo: true,
      logoUrl: '',
      brandName: '', // e.g. 'My App'
      layout: 'centered', // 'centered' | 'split'
      background: {
        type: 'gradient', // 'gradient' | 'image' | 'solid'
        imageUrl: '',
        overlayOpacity: 50,
      },
      card: {
        glass: false,
        glassIntensity: 'medium', // 'subtle' | 'medium' | 'strong'
      },
      split: {
        heroPosition: 'left', // 'left' | 'right'
        heroImageUrl: '',
        headline: '',
        subheadline: '',
        features: [],
      },
      form: {
        icon: '',
        showSeparator: true,
      },
    },
  },
})

endpoints: {
  login: '/auth/login',
  signup: '/auth/signup',
  logout: '/auth/logout',
  refresh: '/auth/refresh',
  me: '/auth/me',
  forgotPassword: '/auth/forgot-password',
  resetPassword: '/auth/reset-password',
}

fieldMapping: {
  id: 'sub',           // default tries: id, sub, user_id
  name: 'full_name',   // default tries: displayName, name, full_name, fullName
  avatar: 'image',     // default tries: avatarUrl, image, profile_picture
  emailVerified: 'verified',
}

const {
  // State
  user,            // Ref<AuthUser | null>
  isLoading,       // Ref<boolean>
  isAuthenticated, // ComputedRef<boolean>
  emailSent,       // Ref<boolean> — true after forgotPassword/sendMagicLink
  codeSent,        // Ref<boolean> — true after sendOtp

  // Core
  login,           // (email, password) => Promise<AuthUser | null>
  signup,          // (email, password) => Promise<AuthUser | null>
  logout,          // () => Promise<boolean>

  // Password
  forgotPassword,  // (email) => Promise<boolean>
  resetPassword,   // (code, newPassword) => Promise<true | { error }>

  // OAuth
  loginWithProvider, // (providerName, options?) => Promise<boolean>

  // OTP
  sendOtp,         // (email) => Promise<boolean>
  verifyOtp,       // (code) => Promise<AuthUser | null>

  // Magic Link
  sendMagicLink,           // (email, options?) => Promise<boolean>
  handleMagicLinkCallback, // (code) => Promise<true | { error }>

  // Utilities
  getCurrentUser,  // () => Promise<AuthUser | null>
  getToken,        // () => Promise<string | null>
  getAuthHeaders,  // () => Promise<Record<string, string>>
  resetState,      // () => void

  // Info
  providerType,    // AuthProviderType
  config,          // ComputedRef<AuthConfig>
} = useXAuth()

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

// Login
const user = await login('user@example.com', 'password')

// OAuth
await loginWithProvider('google')

// OTP flow
await sendOtp('user@example.com')   // sends code
await verifyOtp('123456')           // signs in

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

// Get token for API calls
const headers = await getAuthHeaders()
// { Authorization: 'Bearer eyJ...' }

// app/app.config.ts
export default defineAppConfig({
  xAuth: {
    middleware: {
      enabled: true,        // false disables the global guard entirely —
                            // manage protection yourself (e.g. definePageMeta middleware)
      guestOnly: undefined, // set to replace the built-in guest-only list
      public: undefined,    // set to extend the public list
    },
  },
})

// app/app.config.ts
export default defineAppConfig({
  xAuth: {
    pages: {
      login: true,
      signup: true,
      forgotPassword: true,
      resetPassword: true,
      magicLink: true,
      otp: true,
    },
  },
})