@xenterprises/nuxt-x-auth-better

@xenterprises/nuxt-x-auth-better

BetterAuth authentication layer for Nuxt 4. Pre-built UI components, route protection, OAuth, magic link, and password reset flows — all configurable via app.config.ts.

Install

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

// app.config.ts
export default defineAppConfig({
  xAuth: {
    features: {
      oauth: true,
      magicLink: true,
      forgotPassword: true,
      signup: true,
    },
    redirects: {
      afterLogin: '/dashboard',
      afterSignup: '/dashboard',
    },
    oauthProviders: [
      { id: 'google', label: 'Google', icon: 'i-simple-icons-google' },
      { id: 'github', label: 'GitHub', icon: 'i-simple-icons-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

<script setup>
const {
  user,
  isAuthenticated,
  isLoading,
  login,
  signup,
  logout,
  loginWithProvider,
  sendMagicLink,
  forgotPassword,
  resetPassword,
  changePassword,
  updateUser,
  deleteAccount,
  getToken,
  getAuthHeaders,
} = useXAuth()

await login('email@example.com', 'password')
await loginWithProvider('google')
await sendMagicLink('email@example.com')
await signup('email@example.com', 'password', 'John Doe')
await forgotPassword('email@example.com')
await changePassword('oldpass', 'newpass')
await updateUser({ name: 'New Name' })
await logout()
</script>

Options (app.config.ts)

xAuth.publicRoutes

Array of extra route paths treated as public by the global auth middleware (merged with the built-in defaults /auth/handler and /auth/logout). Entries match by exact path or path prefix.

xAuth: {
  publicRoutes: ['/docs', '/pricing'],
}

xAuth.plugins

Opt-in Better Auth client plugins, resolved when the auth client singleton is created.

xAuth.redirects

xAuth.features

xAuth.oauthProviders

Array of { id, label, icon } objects. Supported provider IDs: google, github, microsoft, facebook, twitter, apple, linkedin, discord, spotify.

xAuth.ui

Composable: useXAuth()

Reactive State

Methods

AuthUser Type

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

Components

Pages (auto-registered)

All other routes are protected (require authentication).

Environment Variables

The auth path is configurable via runtimeConfig.public.x.auth.authPath (default: /auth).

Error Reference

All errors are displayed as toast notifications. Methods return null, false, or { error: string } on failure.

How It Works

This layer uses Better Auth's official Vue client (better-auth/vue) via createAuthClient. The client communicates with your Better Auth backend using cookie-based sessions (credentials: 'include').

1. Session management: createAuthClient is instantiated once (singleton) and provides a reactive useSession() ref that auto-updates. The composable wraps this with convenience methods.

2. Route protection: A global middleware (auth.global.ts) runs on every navigation. It classifies routes as public, guest-only, or protected, then calls getCurrentUser() to check auth state.

3. Auth layout: All /auth/* pages use the auth layout which provides a card-style UI with background image, branding, and animations.

4. OAuth flow: loginWithProvider() calls Better Auth's signIn.social() which redirects to the provider. The callback lands on /auth/handler/oauth-callback where the Handler component refreshes the session.

5. Token access: getToken() and getAuthHeaders() extract the access token from the Better Auth session for use with your own API calls.

Organizations & Teams

The layer includes a full BetterAuth Organizations & Teams implementation. Enable it in app.config.ts:

xAuth: {
  features: {
    organization: true,
    teams: true,
  },
  organization: {
    enabled: true,
    teams: true,
  },
}

useOrganization() Composable

<script setup>
const {
  // State
  organizations,
  organizationsLoading,
  activeOrganization,
  activeLoading,
  activeMember,
  activeMemberRole,
  members,
  invitations,
  teams,
  isOrgAdmin,
  isOrgOwner,
  canCreateOrganization,

  // Org CRUD
  createOrganization,
  updateOrganization,
  deleteOrganization,
  setActiveOrganization,
  getFullOrganization,
  checkSlug,

  // Members
  listMembers,
  updateMemberRole,
  removeMember,
  leaveOrganization,

  // Invitations
  inviteMember,
  cancelInvitation,
  acceptInvitation,
  rejectInvitation,
  getInvitation,
  listInvitations,
  listUserInvitations,

  // Teams
  listTeams,
  createTeam,
  updateTeam,
  deleteTeam,
  setActiveTeam,
  listTeamMembers,
  addTeamMember,
  removeTeamMember,
  listUserTeams,

  // Access control
  hasPermission,
  checkRolePermission,
  getDefaultPermissions,
} = useOrganization()
</script>

Reactive State

Methods

Components

Pages (auto-registered)

Middleware

organization.global.ts runs on every navigation. For routes under /org (or any path configured in organization.protectedRoutes), it:

1. Verifies organizations are enabled.
2. Redirects unauthenticated users to the login page.
3. Resolves the requested organization by slug and sets it active.
4. Redirects non-members to the notMember redirect path.
5. Enforces requireOwner, requireAdmin, and requiredPermissions rules on matched OrganizationRoute objects.

Server Setup & Custom Roles

Add the organization plugin to your BetterAuth server config and enable teams on both server and client:

// server/auth.ts
import { betterAuth } from 'better-auth'
import { organization } from 'better-auth/plugins'

export const auth = betterAuth({
  plugins: [
    organization({
      allowUserToCreateOrganization: true,
      teams: {
        enabled: true,
      },
    }),
  ],
})

Custom access-control roles must be configured on both server and client. See INTEGRATION.md for details.

Layer Architecture

• nuxt.config.ts: Registers @nuxt/ui module, loads the auth CSS, and defines runtimeConfig.public.x.auth for base URL and auth path.
• app/app.config.ts: Defines all configurable options (publicRoutes, plugins, redirects, features, OAuth providers, UI settings) with defaults. Consumer apps override these in their own app.config.ts.
• app/composables/useXAuth.ts: Core composable wrapping Better Auth's Vue client with typed methods for all auth flows.
• app/middleware/auth.global.ts: Global route middleware for auth-based route protection.
• app/plugins/auth-token.ts: Provides $getAuthToken for use in other plugins/composables.
• app/layouts/auth.vue: Visual auth layout with card design, background image, and branding.
• app/components/XAuth/*: Pre-built form components using Nuxt UI's UAuthForm.
• app/pages/auth/*: Auto-registered auth pages.
• app/utils/: Field normalization utilities.

Testing

npm run test        # Watch mode
npm run test:run    # Single run

Requirements

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

License

UNLICENSED