Configuration

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

Configuration

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

app.config.ts

export default defineAppConfig({
  xAuth: {
    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: [],

    ui: {
      showLogo: true,
      showBrandName: true,
      brandName: '',
      tagline: '',
      layout: 'centered', // 'centered' | 'split'
      background: {
        enabled: true,
        imageUrl: '',
        overlayOpacity: 55,
        blur: true,
      },
      card: {
        glass: false,
      },
      split: {
        heroPosition: 'left', // 'left' | 'right'
        headline: '',
        features: [],
      },
      legal: {
        copyright: '',
        links: [],
      },
    },
  },
})

Schema Reference

`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 input on auth forms.
`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-simple-icons-google'`).

`ui`

Key	Type	Default	Description
`ui.showLogo`	`boolean`	`true`	Show logo on auth pages.
`ui.showBrandName`	`boolean`	`true`	Show brand name on auth pages.
`ui.brandName`	`string`	`''`	Brand name text displayed on auth pages.
`ui.tagline`	`string`	`''`	Tagline shown below the brand name.
`ui.layout`	`'centered' \| 'split'`	`'centered'`	Auth page layout style.
`ui.background.enabled`	`boolean`	`true`	Show background decoration on auth pages.
`ui.background.imageUrl`	`string`	`''`	Background image URL.
`ui.background.overlayOpacity`	`number`	`55`	Overlay opacity over the background image (0–100).
`ui.background.blur`	`boolean`	`true`	Apply blur to the background image.
`ui.card.glass`	`boolean`	`false`	Apply glassmorphism effect to the auth card.
`ui.split.heroPosition`	`'left' \| 'right'`	`'left'`	Position of the hero panel in split layout.
`ui.split.headline`	`string`	`''`	Headline text in the split layout hero panel.
`ui.split.features`	`string[]`	`[]`	Feature list displayed in the split layout hero panel.
`ui.legal.copyright`	`string`	`''`	Copyright text displayed in the auth page footer.
`ui.legal.links`	`{ label: string, to: string }[]`	`[]`	Footer legal links (e.g. Privacy Policy, Terms).

Runtime Config (Environment Variables)

The auth API connection is configured via runtimeConfig in nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [['@xenterprises/nuxt-x-auth-better', { install: true }]],
  runtimeConfig: {
    public: {
      x: {
        auth: {
          baseUrl: process.env.NUXT_PUBLIC_AUTH_BASE_URL || '',
          authPath: '/auth',
        },
      },
    },
  },
})

Key	Env Variable	Default	Description
`public.x.auth.baseUrl`	`NUXT_PUBLIC_AUTH_BASE_URL`	`''`	Base URL of the Fastify API server (e.g. `https://api.example.com`).
`public.x.auth.authPath`	—	`'/auth'`	Better Auth mount path on the API server. The full auth URL is `baseUrl + authPath`.

Variable	Required	Description
`NUXT_PUBLIC_AUTH_BASE_URL`	Yes	Base URL of the Fastify API server (e.g. `https://api.example.com`).

AI Context

package: "@xenterprises/nuxt-x-auth-better"
config-key: xAuth
use-when: >
  Configuring redirect paths, enabling/disabling features (OAuth, magic link,
  OTP, forgot password, signup), listing OAuth providers, or customising UI
  appearance (layout, branding, background, glass card, split panel, legal
  footer) for nuxt-x-auth-better. Set NUXT_PUBLIC_AUTH_BASE_URL to point the
  layer at the Fastify API server running Better Auth.

Edit this pageorReport an issue

useXAuth

Better Auth client wrapper composable — session state, auth methods, and user management for nuxt-x-auth-better.

nuxt-x-auth-local

Self-hosted JWT authentication Nuxt layer — useXAuth composable, 4 pre-built UI components, global route middleware, automatic token refresh, and full endpoint configurability for your own backend.