Configuration

app.config.ts and runtimeConfig reference for @xenterprises/nuxt-x-auth-better, including Organizations & Teams configuration.

Configuration

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

app.config.ts

// app/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,
      organization: false,
      teams: false,
    },

    // Extra routes treated as public by the global auth middleware
    publicRoutes: [],

    // Opt-in better-auth client plugins
    plugins: {
      admin: false,
      stripe: false,
    },

    oauthProviders: [],

    ui: {
      showLogo: true,
      showBrandName: true,
      logoUrl: '',
      brandName: '',
      tagline: '',
      layout: 'centered', // 'centered' | 'split'
      background: {
        enabled: true,
        imageUrl: '',
        overlayOpacity: 55,
        blur: true,
      },
      card: {
        glass: false,
        glassIntensity: 'medium', // 'subtle' | 'medium' | 'strong'
        logoUrl: '',
      },
      split: {
        heroPosition: 'left', // 'left' | 'right'
        heroImageUrl: '',
        headline: '',
        subheadline: '',
        features: [],
      },
      form: {
        icon: '',
        showSeparator: true,
      },
      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.
`features.organization`	`boolean`	`false`	Enable BetterAuth Organizations & Teams.
`features.teams`	`boolean`	`false`	Enable team features (requires `organization: true`).

`publicRoutes`

Key	Type	Default	Description
`publicRoutes`	`string[]`	`[]`	Extra routes treated as public by the `auth.global` middleware, merged with the built-in defaults (`/auth/handler`, `/auth/logout`).

`plugins`

Opt-in Better Auth client plugins, resolved when the auth client singleton is created. Both require the corresponding plugin to also be configured on the Better Auth server.

Key	Type	Default	Description
`plugins.admin`	`boolean`	`false`	Register the Better Auth `adminClient` plugin.
`plugins.stripe`	`boolean`	`false`	Register the Better Auth `stripeClient` plugin. better-auth 1.6.x does not export it (it ships in the community `@better-auth/stripe` package), so the flag is a documented no-op with a console warning when unavailable.

`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.logoUrl`	`string`	`''`	Logo image URL shown above the auth card.
`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.card.glassIntensity`	`'subtle' \| 'medium' \| 'strong'`	`'medium'`	Intensity of the glass effect.
`ui.card.logoUrl`	`string`	`''`	Logo image URL inside the auth card.
`ui.split.heroPosition`	`'left' \| 'right'`	`'left'`	Position of the hero panel in split layout.
`ui.split.heroImageUrl`	`string`	`''`	Background image URL for the hero panel.
`ui.split.headline`	`string`	`''`	Headline text in the split layout hero panel.
`ui.split.subheadline`	`string`	`''`	Subheadline text in the split layout hero panel.
`ui.split.features`	`string[]`	`[]`	Feature list displayed in the split layout hero panel.
`ui.form.icon`	`string`	`''`	Iconify icon shown above auth forms.
`ui.form.showSeparator`	`boolean`	`true`	Show the "or" separator between the form and OAuth buttons.
`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).

Configure organization and team behavior. Organizations are enabled with features.organization: true. Teams are enabled by default when organizations are on (organization.teams: true) and controlled by features.teams.

Key	Type	Default	Description
`organization.enabled`	`boolean`	`false`	Enable organization features.
`organization.teams`	`boolean`	`true`	Enable teams within organizations.
`organization.allowUserToCreateOrganization`	`boolean`	`true`	Allow regular users to create organizations.
`organization.requireMemberEmailVerification`	`boolean`	`true`	Require email verification before accepting invitations.
`organization.defaultRole`	`string`	`'member'`	Default role assigned to new members.
`organization.protectedRoutes`	`Array<string \| OrganizationRoute>`	`['/org']`	Routes protected by the organization middleware.

protectedRoutes entries can be simple strings (matched by prefix) or OrganizationRoute objects with additional access requirements:

interface OrganizationRoute {
  path: string
  requireOwner?: boolean
  requireAdmin?: boolean
  requireMember?: boolean
  requiredPermissions?: Array<{ permissions: Record<string, string[]> }>
}

xAuth: {
  organization: {
    enabled: true,
    teams: true,
    allowUserToCreateOrganization: true,
    requireMemberEmailVerification: true,
    defaultRole: 'member',
    protectedRoutes: [
      '/org',
      { path: '/org/:slug/settings', requireOwner: true },
      { path: '/org/:slug/billing', requireAdmin: true },
    ],
    redirects: {
      create: '/org/create',
      list: '/org',
      settings: '/org/:slug/settings',
      invitations: '/org/:slug/invitations',
      notMember: '/org',
      noPermission: '/org',
    },
  },
}

`organization.redirects`

Key	Type	Default	Description
`organization.redirects.create`	`string`	`'/org/create'`	Path to create a new organization.
`organization.redirects.list`	`string`	`'/org'`	Path to the organization list / switcher.
`organization.redirects.settings`	`string`	`'/org/:slug/settings'`	Path to organization settings.
`organization.redirects.invitations`	`string`	`'/org/:slug/invitations'`	Path to pending invitations.
`organization.redirects.notMember`	`string`	`'/org'`	Redirect when the user is not a member of the requested organization.
`organization.redirects.noPermission`	`string`	`'/org'`	Redirect when the user lacks the required role or permission.

Runtime Config (Environment Variables)

The auth API connection is configured via runtimeConfig.public.x.auth. The layer declares the schema itself, so the standard Nuxt environment variables are picked up automatically — no consumer runtimeConfig wiring needed:

# .env
NUXT_PUBLIC_X_AUTH_BASE_URL=https://api.example.com
# NUXT_PUBLIC_X_AUTH_AUTH_PATH=/auth   (optional, this is the default)

Point baseUrl at the Better Auth backend, never at the Nuxt app itself — a self-referencing base URL makes SSR session probes recurse (/auth/get-session → 404 page → middleware → fetch …) and hangs the server render. For same-origin proxy setups, leave baseUrl empty.

To map a differently-named variable, override runtimeConfig in the consumer's nuxt.config.ts:

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

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

Variable	Required	Description
`NUXT_PUBLIC_X_AUTH_BASE_URL`	Yes	Base URL of the Better Auth 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, organization, teams), listing OAuth providers,
  customising UI appearance (layout, branding, background, glass card, split
  panel, legal footer), or configuring Organizations & Teams settings
  (protected routes, redirects, roles, team support), enabling better-auth
  client plugins (admin, stripe), or declaring extra public routes for
  nuxt-x-auth-better.
  Set NUXT_PUBLIC_X_AUTH_BASE_URL to point the layer at the Better Auth API
  server.

Edit this pageorReport an issue

useOrganization

Better Auth Organizations & Teams composable for nuxt-x-auth-better — org management, members, invitations, teams, and access control.

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.