Configuration

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

Configuration

How to configure this module via app.config.ts and environment variables.

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: 'My App',
      tagline: 'Welcome back',
      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,
      },
    },

    // Optional: endpoint overrides for 'local' provider or custom backends
    endpoints: {
      login: '/auth/login',
      signup: '/auth/signup',
      logout: '/auth/logout',
      refresh: '/auth/refresh',
      me: '/auth/me',
      forgotPassword: '/auth/forgot-password',
      resetPassword: '/auth/reset-password',
    },

    // Optional: field mapping to normalize provider-specific user shapes
    fieldMapping: {
      id: 'sub',
      name: 'full_name',
      avatar: 'image',
      emailVerified: 'verified',
    },
  },
})

Schema Reference

Top-level

Key	Type	Default	Description
`xAuth.provider`	`'stack' \| 'better-auth' \| 'neon-auth' \| 'local'`	`'stack'`	Auth backend to use. Determines which provider adapter is loaded.

`redirects`

Key	Type	Default	Description
`redirects.login`	`string`	`'/auth/login'`	Path to the login page.
`redirects.signup`	`string`	`'/auth/signup'`	Path to the signup page.
`redirects.afterLogin`	`string`	`'/'`	Redirect destination after successful login.
`redirects.afterSignup`	`string`	`'/'`	Redirect destination after successful signup.
`redirects.afterLogout`	`string`	`'/auth/login'`	Redirect destination after logout.
`redirects.forgotPassword`	`string`	`'/auth/forgot-password'`	Path to the forgot password page.

`features`

Key	Type	Default	Description
`features.oauth`	`boolean`	`false`	Show OAuth provider buttons on auth forms.
`features.magicLink`	`boolean`	`false`	Show magic link option on login form.
`features.otp`	`boolean`	`false`	Show OTP verification option.
`features.forgotPassword`	`boolean`	`true`	Show forgot password link on login form.
`features.signup`	`boolean`	`true`	Show signup link on login form.

`oauthProviders`

An array of OAuth provider definitions rendered by <XAuthOAuthButtonGroup />:

Field	Type	Description
`id`	`string`	Provider ID (e.g. `'google'`, `'github'`).
`label`	`string`	Display label on the button.
`icon`	`string`	Iconify icon string (e.g. `'i-logos-google-icon'`).

`tokens`

Key	Type	Default	Description
`tokens.accessCookie`	`string`	`'x_auth_access'`	Cookie name for the access token.
`tokens.refreshCookie`	`string`	`'x_auth_refresh'`	Cookie name for the refresh token.
`tokens.hasRefresh`	`boolean`	`true`	Whether the provider issues a separate refresh token.

`ui`

Key	Type	Default	Description
`ui.showLogo`	`boolean`	`true`	Show logo on auth pages.
`ui.logoUrl`	`string`	`''`	URL of the logo image.
`ui.brandName`	`string`	`'My App'`	Brand name displayed on auth pages.
`ui.tagline`	`string`	`'Welcome back'`	Tagline shown below the brand name.
`ui.layout`	`'centered' \| 'split'`	`'centered'`	Auth page layout style.
`ui.background.type`	`'gradient' \| 'image' \| 'solid'`	`'gradient'`	Background style for auth pages.
`ui.background.imageUrl`	`string`	`''`	Background image URL (used when `type` is `'image'`).
`ui.background.overlayOpacity`	`number`	`50`	Overlay opacity over background image (0–100).
`ui.card.glass`	`boolean`	`false`	Apply glassmorphism effect to the auth card.
`ui.card.glassIntensity`	`'subtle' \| 'medium' \| 'strong'`	`'medium'`	Intensity of the glass effect.
`ui.split.heroPosition`	`'left' \| 'right'`	`'left'`	Position of the hero panel in split layout.
`ui.split.heroImageUrl`	`string`	`''`	Hero panel background image URL.
`ui.split.headline`	`string`	`''`	Headline text in the split layout hero.
`ui.split.subheadline`	`string`	`''`	Subheadline text in the split layout hero.
`ui.split.features`	`string[]`	`[]`	Feature list displayed in the split layout hero.
`ui.form.icon`	`string`	`''`	Icon shown at the top of the auth form.
`ui.form.showSeparator`	`boolean`	`true`	Show an "or" separator between password and OAuth sections.

`endpoints` (optional — Local JWT / custom backends)

Key	Type	Default	Description
`endpoints.login`	`string`	`'/auth/login'`	Login API endpoint.
`endpoints.signup`	`string`	`'/auth/signup'`	Signup API endpoint.
`endpoints.logout`	`string`	`'/auth/logout'`	Logout API endpoint.
`endpoints.refresh`	`string`	`'/auth/refresh'`	Token refresh endpoint.
`endpoints.me`	`string`	`'/auth/me'`	Current user endpoint.
`endpoints.forgotPassword`	`string`	`'/auth/forgot-password'`	Forgot password endpoint.
`endpoints.resetPassword`	`string`	`'/auth/reset-password'`	Password reset endpoint.

`fieldMapping` (optional)

Maps provider-specific field names to the unified AuthUser shape:

Key	Type	Description
`fieldMapping.id`	`string`	Field name for the user ID (tries `id`, `sub`, `user_id` by default).
`fieldMapping.name`	`string`	Field name for the display name (tries `displayName`, `name`, `full_name`, `fullName`).
`fieldMapping.avatar`	`string`	Field name for the avatar URL (tries `avatarUrl`, `image`, `profile_picture`).
`fieldMapping.emailVerified`	`string`	Field name for email verification status.

Runtime Config (Environment Variables)

Configure the active auth provider via environment variables:

Variable	Provider	Required	Description
`NUXT_PUBLIC_STACK_PROJECT_ID`	Stack Auth	Yes	Stack project ID.
`NUXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY`	Stack Auth	Yes	Publishable client key.
`NUXT_PUBLIC_BETTER_AUTH_BASE_URL`	Better Auth	Yes	Better Auth API base URL.
`NUXT_PUBLIC_NEON_AUTH_PROJECT_ID`	Neon Auth	Yes	Neon project ID.
`NUXT_PUBLIC_NEON_AUTH_BRANCH_ID`	Neon Auth	Yes	Neon branch ID.
`NUXT_PUBLIC_NEON_AUTH_BASE_URL`	Neon Auth	Yes	Neon Auth base URL.
`NUXT_PUBLIC_LOCAL_AUTH_BASE_URL`	Local JWT	Yes	Your local API base URL.

AI Context

package: "@xenterprises/nuxt-x-auth"
config-key: xAuth
use-when: >
  Configuring auth provider, redirect paths, feature flags (OAuth, magic link,
  OTP, forgot password), OAuth provider list, cookie names, or UI appearance
  (layout, branding, background, glass card, split panel) for nuxt-x-auth.
  Also use when overriding API endpoints for local/custom JWT backends or
  normalizing provider field names via fieldMapping.

Edit this pageorReport an issue

useXAuth

Provider-agnostic authentication composable — unified interface for Stack Auth, Better Auth, Neon Auth, and Local JWT backends.

nuxt-x-auth-better

Nuxt 4 authentication layer powered by Better Auth — 7 XAuth-prefixed components, a useXAuth composable, global auth middleware, 6 pre-built pages, and a fully typed app.config.ts interface built on Nuxt UI v4.