Configuration
app.config.ts and runtimeConfig reference for @xenterprises/nuxt-x-auth-local.
Configuration
app.config.ts
export default defineAppConfig({
xAuth: {
tokens: {
accessCookie: 'x_auth_access', // cookie name for access token
refreshCookie: 'x_auth_refresh', // cookie name for refresh token
hasRefresh: true, // set false if your API has no refresh token
},
redirects: {
login: '/auth/login',
signup: '/auth/signup',
afterLogin: '/',
afterSignup: '/',
afterLogout: '/auth/login',
forgotPassword: '/auth/forgot-password',
},
features: {
forgotPassword: true,
signup: true,
routeProtection: true, // set false to disable the global route middleware
},
ui: {
showLogo: true,
logoUrl: undefined, // e.g. '/logo.svg'
brandName: undefined, // e.g. 'Acme' — shown above the auth card
tagline: undefined, // shown under the brand name
form: {
icon: undefined, // e.g. 'i-lucide-shield'; per-form fallbacks apply
showSeparator: true, // separator above form footer links
},
},
},
})
Schema Reference
| Key | Type | Default | Description |
|---|---|---|---|
tokens.accessCookie | string | 'x_auth_access' | Cookie name for storing the access token. |
tokens.refreshCookie | string | 'x_auth_refresh' | Cookie name for storing the refresh token. |
tokens.hasRefresh | boolean | true | Set false if your API does not issue a refresh token. |
redirects.login | string | '/auth/login' | Path of the login page. |
redirects.signup | string | '/auth/signup' | Path of the signup page. |
redirects.afterLogin | string | '/' | Redirect destination after a successful login. |
redirects.afterSignup | string | '/' | Redirect destination after a successful signup. |
redirects.afterLogout | string | '/auth/login' | Redirect destination after logout. |
redirects.forgotPassword | string | '/auth/forgot-password' | Path of the forgot-password page. |
features.forgotPassword | boolean | true | Enable forgot-password flow. |
features.signup | boolean | true | Enable signup page and link. |
features.routeProtection | boolean | true | Enable the global route middleware. Set false to manage your own route guards. |
ui.showLogo | boolean | true | Show a logo in the auth layout header (requires ui.logoUrl). |
ui.logoUrl | string | undefined | Logo image URL shown in the auth layout header. |
ui.brandName | string | undefined | Brand name shown above the auth card. |
ui.tagline | string | undefined | Tagline shown under the brand name. |
ui.form.icon | string | undefined | Iconify icon shown above each auth form (e.g. 'i-lucide-shield'). Each form falls back to its own default icon. |
ui.form.showSeparator | boolean | true | Show a separator above the form footer links. |
Earlier 1.0 releases also declared
ui.layout / ui.background.* / ui.card.* / ui.split.* keys. They were never consumed by any component and were removed in the batteries-included audit (plan 18) — setting them now has no effect and they are no longer part of the typed AuthConfig. A split/hero auth layout variant is on the feature backlog.Runtime Config / Environment Variables
Configure endpoints in nuxt.config.ts under runtimeConfig.public.localAuth. Each key maps to a NUXT_PUBLIC_LOCAL_AUTH_* environment variable.
| Variable | Required | Description |
|---|---|---|
NUXT_PUBLIC_LOCAL_AUTH_BASE_URL | Yes* | Backend API base URL. *May be left empty for a same-origin API. |
NUXT_PUBLIC_LOCAL_AUTH_LOGIN_ENDPOINT | No | Override default /auth/login. |
NUXT_PUBLIC_LOCAL_AUTH_SIGNUP_ENDPOINT | No | Override default /auth/signup. |
NUXT_PUBLIC_LOCAL_AUTH_LOGOUT_ENDPOINT | No | Override default /auth/logout. |
NUXT_PUBLIC_LOCAL_AUTH_REFRESH_ENDPOINT | No | Override default /auth/refresh. |
NUXT_PUBLIC_LOCAL_AUTH_USER_ENDPOINT | No | Override default /auth/me. |
NUXT_PUBLIC_LOCAL_AUTH_FORGOT_PASSWORD_ENDPOINT | No | Override default /auth/forgot-password. |
NUXT_PUBLIC_LOCAL_AUTH_RESET_PASSWORD_ENDPOINT | No | Override default /auth/reset-password. |
NUXT_PUBLIC_LOCAL_AUTH_CHANGE_PASSWORD_ENDPOINT | No | Override default /auth/change-password. |
runtimeConfig.public.localAuth defaults
| Key | Default | Description |
|---|---|---|
baseUrl | "" | Backend API base URL. Leave empty for a same-origin API. |
loginEndpoint | "/auth/login" | POST endpoint for email/password login. |
signupEndpoint | "/auth/signup" | POST endpoint for registration. |
logoutEndpoint | "/auth/logout" | POST endpoint for logout. |
refreshEndpoint | "/auth/refresh" | POST endpoint for token refresh. |
userEndpoint | "/auth/me" | GET endpoint to fetch the current user. |
forgotPasswordEndpoint | "/auth/forgot-password" | POST endpoint to request a reset email. |
resetPasswordEndpoint | "/auth/reset-password" | POST endpoint to apply a new password. |
changePasswordEndpoint | "/auth/change-password" | POST endpoint for authenticated password change. |
AI Context
package: "@xenterprises/nuxt-x-auth-local"
config-key: xAuth
runtime-config-key: localAuth
use-when: >
Configuring cookie names, redirect paths, feature flags (forgot password,
signup), or UI appearance for nuxt-x-auth-local. Set NUXT_PUBLIC_LOCAL_AUTH_BASE_URL
and optional endpoint overrides via runtimeConfig.public.localAuth to point
the layer at your self-hosted JWT API server.
useXAuth
Self-hosted JWT authentication composable with useState shared state, automatic token refresh on 401, and full auth method coverage.
nuxt-x-auth-stack
Nuxt 4 authentication layer powered by Stack Auth — 10 XAuth-prefixed components, a useXAuth composable with OAuth/magic-link/OTP/password-reset support, global auth middleware, and 7 pre-built pages built on Nuxt UI v4.
