talon-auth-nuxt

Nuxt module for integrating Talon authentication into your Nuxt application.

Installation

pnpm add talon-auth-nuxt talon-auth

Setup

1. Register the module

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['talon-auth-nuxt'],

  talon: {
    appId: process.env.TALON_APP_ID,
    apiUrl: process.env.API_URL // defaults to https://api.talon.codes
  }
})

2. Add the login component to your page

<script setup lang="ts">
// Import the talon-auth login web component (client-side only)
if (import.meta.client) {
  await import('talon-auth/login')
}

const config = useRuntimeConfig()
const { appId, apiUrl } = config.public.talon!
const user = useTalonUser()

onMounted(() => setupTalonLogin())
</script>

<template>
  <talon-login :app-id="appId" :api-url="apiUrl" @login="onLogin" />

  <div v-if="user">
    Welcome, {{ user.email }}
    <button @click="logout">Logout</button>
  </div>
</template>

Configuration

| Option | Type | Default | Description | | -------------------- | -------- | ------------------------- | ------------------------------------- | | appId | string | required | Your Talon application ID | | apiUrl | string | https://api.talon.codes | Talon API URL | | authEndpoint | string | /api/auth | Server endpoint for cookie management | | loginComponentName | string | talon-login | Custom element tag name | | cookie | object | see below | Cookie configuration |

Cookie Configuration

cookie: {
  name: 'talon_auth',      // Cookie name
  httpOnly: true,          // HTTP-only cookie
  secure: true,            // Secure in production
  sameSite: 'lax',         // SameSite policy
  maxAge: 60 * 60 * 24 * 7, // 7 days
  path: '/'                // Cookie path
}

Composables

The module auto-imports the following composables:

useTalonUser()

Returns a readonly ref of the current authenticated user.

const user = useTalonUser()
// user.value is TalonAuthUser | null

useTalonLogout()

Returns a logout function that clears the session.

const logout = useTalonLogout()
await logout()

setupTalonLogin()

Call this in onMounted to initialize the login flow and sync authentication state.

onMounted(() => setupTalonLogin())

getLoginEl()

Returns the <talon-login> DOM element. Useful for accessing the component's methods directly.

const loginEl = getLoginEl()
const token = await loginEl.getAccessToken()

How It Works

1. Server-side: On each request, the module's server plugin verifies the auth cookie and populates the user state for SSR.

2. Client-side: When setupTalonLogin() is called, it syncs with the <talon-login> component and updates the server cookie.

3. Cookie management: The module registers server handlers at the configured authEndpoint:

   • POST /api/auth - Verifies token and sets the auth cookie
   • DELETE /api/auth - Clears the auth cookie

TypeScript

The module exports types from talon-auth:

import type { TalonAuthUser, TalonLoginComponent } from 'talon-auth-nuxt'