nuxt-x-auth-nile

Nuxt 4 SPA layer for Nile Auth via @niledatabase/client (^5.3.1). Ships branded auth pages, 20 XAuth* components, multi-tenancy management, email verification gate, two-factor authentication, magic links, useXAuth / useXTenant / useXNileApi, and a global route guard. Pair it with @xenterprises/fastify-xauth-nile on a same-origin /api — browser requests talk to same-origin cookie endpoints.

The layer runs in ssr: false mode. There is no server/ directory and no @niledatabase/server here.

0.2.0. Unified useXAuth (removed useXNileAuth), multi-tenancy (useXTenant + org pages), useXNileApi on ofetch, email-verification gate default on. SHA 1324148.

Installation

npm install @xenterprises/nuxt-x-auth-nile

Peer dependencies: nuxt ^4, @nuxt/ui ^4, tailwindcss ^4, @tailwindcss/vite ^4.

What the consumer writes

1. nuxt.config.ts — extend the layer:

export default defineNuxtConfig({
  extends: ["@xenterprises/nuxt-x-auth-nile"],
})

2. app/app.config.ts — optional configuration overrides:

export default defineAppConfig({
  ui: {
    colors: { primary: "emerald" },
  },
  xAuth: {
    redirects: { afterLogin: "/dashboard" },
    features: {
      oauth: true,
      mfa: true,
      magicLink: true,
      requireEmailVerified: true,
      forgotPassword: true,
      signup: true,
    },
    tenant: {
      enabled: true,
      required: false,
      signup: {
        collectName: "optional", // "off" | "optional" | "required"
      },
    },
    oauthProviders: [
      { id: "google", label: "Google", icon: "i-simple-icons-google" },
      { id: "github", label: "GitHub", icon: "i-simple-icons-github" },
    ],
  },
})

3. .env — origin and path the browser calls:

# Empty = current page origin (same-host Fastify or proxy)
NUXT_PUBLIC_NILE_BASE_URL=
NUXT_PUBLIC_NILE_BASE_PATH=/api

Key Capabilities (0.2.0)

• Multi-Tenancy: Complete organization lifecycle (creation, selector, members, rename, leave, delete) with cookie synchronization (nile.tenant-id) and request header injection (x-tenant-id).
• Email Verification Gate: Enabled by default; unverified users are directed to /auth/verify-email with resend cooldown and status check.
• Two-Factor Authentication: Authenticator app setup with QR code + key, challenge on sign-in, and removal verification dialog.
• Magic Links: Passwordless sign-in via email.
• Shared Reactive State: Persistent useState keys prevent state divergence across components and pages.
• Return URL Preservation: Unauthenticated redirects preserve target route via ?redirect=... query parameters with isSafeRedirect validation.

Provided Plugins

• $getAuthToken: Returns null (Nile uses HTTP cookies).
• $getCurrentUser: Returns the active NileUser.
• $logout: Signs out and clears state.
• $xTenantId: Reactive Ref<string | null> of the active organization ID.
• $xTenantHeaders(): Returns { [headerName]: id } for API requests.