Nuxt quickstart

The @authdog/nuxt SDK adds browser authentication state to Nuxt through a Vue plugin and composables, plus Nitro helpers for reading and clearing the authdog-session cookie.

@authdog/nuxt is not yet published to npm (npm view @authdog/nuxt returns 404 at the time of writing). Version 0.1.0 is set to publish publicly from the web-sdk repository, so install it from there until it lands on the registry.

Install

npm install @authdog/nuxt

yarn add @authdog/nuxt

pnpm add @authdog/nuxt

bun add @authdog/nuxt

deno add npm:@authdog/nuxt

Requires Vue ^3.5 (provided by Nuxt). The package ships two entry points: @authdog/nuxt (plugin and composables) and @authdog/nuxt/server (Nitro helpers). Expose your environment's public key (pk_...) through Nuxt runtime config, for example as runtimeConfig.public.authdogPublicKey.

Register the plugin

createAuthdog validates the public key once and throws on startup if it is missing, malformed, or points at an untrusted identity host:

// plugins/authdog.ts
import { createAuthdog } from "@authdog/nuxt"

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()
  nuxtApp.vueApp.use(
    createAuthdog({ publicKey: config.public.authdogPublicKey as string }),
  )
})

On the client the plugin accepts a ?token= only when it has three JWT-shaped segments, stores it in localStorage, strips it from the URL, and reloads once. A value that is not JWT-shaped is stripped and discarded. This check is not signature, issuer, audience, or expiry validation. Otherwise the plugin hydrates the token from localStorage.

Composables

Each composable throws if the plugin is not installed.

load() calls the OIDC userinfo endpoint with the stored token and never throws. It resolves to null and sets error on failure. signIn and signUp redirect the browser to the OIDC authorize flow (sign-up adds prompt=signup); redirectUri defaults to window.location.origin. The public key comes from the plugin, so you do not pass it.

<script setup lang="ts">
import { useSession, useUser, useSignIn, useSignOut } from "@authdog/nuxt"

const { session, isLoading } = useSession()
const { user, load } = useUser()
const { signIn } = useSignIn()
const { signOut } = useSignOut()
</script>

<template>
  <button v-if="!session.isAuthenticated" @click="signIn()">Sign in</button>
  <template v-else>
    <button @click="load()">Load profile</button>
    <button @click="signOut('/')">Sign out</button>
    <pre>{{ user }}</pre>
  </template>
</template>

Server helpers

Import from @authdog/nuxt/server in Nitro routes:

// server/api/me.ts
import { getServerSession } from "@authdog/nuxt/server"

export default defineEventHandler((event) => {
  const token = getServerSession(event)
  return { authenticated: !!token }
})

• getServerSession(event) accepts an H3 event or a Web Request and returns the raw authdog-session cookie value, or null. It performs no validation.
• logoutResponse(request) returns a 302 that clears the authdog-session cookie and redirects to the sanitized redirect_uri query parameter, defaulting to /. Secure is added only when NODE_ENV is production.
• getServerSidePayloadPublicKey(publicKey) returns the validated public-key payload as a JSON string.

Sign out

useSignOut().signOut() clears only the browser token in localStorage, and navigates to redirectTo if given. To clear the server cookie, route the user through a handler that returns logoutResponse(request).

Caveats

• The plugin does not set the authdog-session cookie, and no cookie callback exchange is included. For server-side authentication, set an HttpOnly cookie after validating the token with a backend SDK.
• session.isAuthenticated reflects token presence only. Treat composable state and getServerSession() as untrusted input, and enforce authorization in server routes.

Next steps

• Sign up & sign in: the flows the plugin drives.
• Backend requests: validate sessions on your API.