@xenterprises/nuxt-x-auth-stack

Stack Auth authentication layer for Nuxt 4 with OAuth, OTP, and Magic Link support.

Features

• Drop-in authentication - Works out of the box with just 2 env vars
• Stack Auth SDK - Uses @stackframe/js with automatic token management
• OAuth support - Google, GitHub, Microsoft, Apple, and more
• Magic Link - Passwordless email authentication
• OTP - One-time password verification
• Pre-built UI - Login, Signup, Forgot Password, OTP, Magic Link pages
• Route protection - Global middleware for authenticated routes
• Nuxt UI v4 - Beautiful, responsive design

Quick Start

1. Install

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

2. Extend the layer

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

3. Add environment variables

# .env
NUXT_PUBLIC_STACK_PROJECT_ID=your-project-id
NUXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=your-publishable-key

Get these values from your Stack Auth dashboard.

That's it! Your app now has full authentication at /auth/login.

Configuration (Optional)

Customize features and UI in app.config.ts:

// app.config.ts
export default defineAppConfig({
  xAuth: {
    // Redirect paths
    redirects: {
      afterLogin: '/dashboard',
      afterSignup: '/onboarding',
      afterLogout: '/auth/login',
    },

    // Enable/disable features
    features: {
      oauth: true,
      magicLink: true,
      otp: true,
      forgotPassword: true,
      signup: true,
    },

    // OAuth providers (requires Stack Auth dashboard setup)
    oauthProviders: [
      { id: 'google', label: 'Google', icon: 'i-simple-icons-google' },
      { id: 'github', label: 'GitHub', icon: 'i-simple-icons-github' },
    ],

    // UI customization
    ui: {
      showLogo: true,
      logoUrl: '/logo.svg',
      brandName: 'My App',
      tagline: 'Welcome back',
      layout: 'centered', // or 'split'
    },
  },
})

Composable API

<script setup>
const {
  // State
  user,
  isLoading,
  isAuthenticated,

  // Auth methods
  login,
  signup,
  logout,
  loginWithProvider,

  // Magic link
  sendMagicLink,
  signInWithMagicLink,

  // OTP
  sendOtp,
  verifyOtp,

  // Password reset
  forgotPassword,
  resetPassword,

  // Token access (for API calls)
  getToken,
  getAuthHeaders,
} = useXAuth()

// Email/password login
await login('[email protected]', 'password')

// Signup
await signup('[email protected]', 'password')

// OAuth (redirects to provider)
await loginWithProvider('google')

// Magic link
await sendMagicLink('[email protected]')

// OTP flow
const nonce = await sendOtp('[email protected]')
await verifyOtp('123456', nonce)

// Get auth headers for API calls
const headers = await getAuthHeaders()
await $fetch('/api/protected', { headers })

// Logout
await logout()
</script>

Components

| Component | Description | |-----------|-------------| | XAuthLogin | Email/password login form with OAuth | | XAuthSignup | Registration form with OAuth | | XAuthForgotPassword | Password reset request | | XAuthOtp | OTP verification flow | | XAuthMagicLink | Magic link authentication | | XAuthHandler | Callback handler for OAuth/Magic Link | | XAuthOAuthButton | Single OAuth provider button | | XAuthOAuthButtonGroup | All configured OAuth buttons |

Pages

These pages are automatically registered:

| Route | Description | |-------|-------------| | /auth/login | Login page | | /auth/signup | Registration page | | /auth/forgot-password | Password reset request | | /auth/otp | OTP authentication | | /auth/magic-link | Magic link authentication | | /auth/logout | Logout handler | | /auth/handler/* | OAuth/Magic Link callbacks |

Route Protection

Routes are protected automatically by global middleware:

• Guest-only - /auth/login, /auth/signup, etc. (redirects authenticated users away)
• Public - /auth/handler/*, /auth/logout (accessible to everyone)
• Protected - All other routes (requires authentication)

Stack Auth Dashboard Setup

1. Create a project at Stack Auth
2. Copy your Project ID and Publishable Client Key
3. Configure OAuth providers if needed (Google, GitHub, etc.)
4. Add your domain to allowed callback URLs:
   • https://yourdomain.com/auth/handler/oauth-callback
   • https://yourdomain.com/auth/handler/magic-link-callback

Requirements

• Nuxt 4+
• @nuxt/ui 4+
• Node.js 18+

License

MIT