@xenterprises/nuxt-x-auth-better

BetterAuth authentication layer for Nuxt 4.

Features

• Better Auth integration - Industry-standard authentication with Better Auth
• OAuth providers - Google, GitHub, and more
• Magic link authentication - Passwordless login via email
• Secure token storage - HttpOnly cookies with SameSite protection
• Field normalization - Unified user object across providers
• Pre-built UI components - Login, Signup, Forgot Password, Magic Link, OAuth
• Route protection - Global middleware for authenticated routes
• Responsive design - Built with Nuxt UI v4

Installation

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

Setup

1. Extend the layer

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

2. Configure your provider

// app.config.ts
export default defineAppConfig({
  xAuth: {
    tokens: {
      accessCookie: 'x_auth_access',
      refreshCookie: 'x_auth_refresh',
      hasRefresh: true,
    },
    redirects: {
      login: '/auth/login',
      signup: '/auth/signup',
      afterLogin: '/dashboard',
      afterSignup: '/dashboard',
      afterLogout: '/auth/login',
      forgotPassword: '/auth/forgot-password',
    },
    features: {
      oauth: true,
      magicLink: true,
      forgotPassword: true,
      signup: true,
    },
    oauthProviders: ['google', 'github'],
    ui: {
      showLogo: true,
      logoUrl: '/logo.svg',
      brandName: 'My App',
    },
  },
})

3. Set environment variables

NUXT_PUBLIC_X_AUTH_BASE_URL=https://api.example.com

Usage

Composable

<script setup>
const {
  user,
  login,
  logout,
  signup,
  loginWithOAuth,
  sendMagicLink,
  forgotPassword,
  isLoading,
  isAuthenticated
} = useXAuth()

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

// OAuth login
await loginWithOAuth('google')

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

// Signup
await signup('[email protected]', 'password', { name: 'John' })

// Password reset
await forgotPassword('[email protected]')

// Logout
await logout()
</script>

Normalized User Object

Better Auth returns a normalized user object:

{
  id: 'user-123',
  email: '[email protected]',
  name: 'John Doe',
  avatar: 'https://example.com/avatar.jpg',
  emailVerified: true,
  metadata: { /* provider-specific data */ }
}

Protected Routes

Routes are automatically protected by the global middleware.

Route types:

• Guest-only routes - /auth/login, /auth/signup, /auth/forgot-password, /auth/magic-link (redirects logged-in users)
• Public routes - /auth/handler/*, /auth/logout (accessible by anyone)
• Protected routes - Everything else (requires authentication)

Components

| Component | Description | |-----------|-------------| | XAuthLogin | Email/password login form | | XAuthSignup | Registration form | | XAuthForgotPassword | Password reset request | | XAuthMagicLink | Magic link authentication | | XAuthOAuthButton | Single OAuth provider button | | XAuthOAuthButtonGroup | All configured OAuth buttons | | XAuthHandler | OAuth callback handler |

Pages (Auto-registered)

• /auth/login - Login page
• /auth/signup - Registration page
• /auth/forgot-password - Password reset
• /auth/magic-link - Magic link authentication
• /auth/logout - Logout handler
• /auth/handler/* - OAuth callback handlers

OAuth Providers

Configure which OAuth providers to show:

// app.config.ts
export default defineAppConfig({
  xAuth: {
    oauthProviders: ['google', 'github', 'microsoft', 'apple'],
  },
})

Available providers depend on your Better Auth backend configuration.

Token Storage

Tokens are stored in secure cookies:

• HttpOnly - Not accessible via JavaScript
• Secure - Only sent over HTTPS in production
• SameSite=Lax - CSRF protection

Cookie names are configurable via tokens.accessCookie and tokens.refreshCookie.

Testing

# Unit tests
npm run test

# E2E tests
npx playwright test

Requirements

• Nuxt 4+
• Better Auth 1.0+
• @nuxt/ui v4+ (included)

License

MIT