Nuxt SDK

The ThunderID Nuxt SDK (@thunderid/nuxt) is a Nuxt module that integrates ThunderID authentication into Nuxt 3 applications. It provides composables, auto-registered components, route middleware, server utilities, and a set of built-in API routes, all with full SSR hydration support.

Installation

Install the ThunderID Nuxt SDK using your preferred package manager:

npm

npm install @thunderid/nuxt

Yarn

yarn add @thunderid/nuxt

pnpm

pnpm add @thunderid/nuxt

Bun

bun add @thunderid/nuxt

Getting Started

Register the module and provide your application credentials in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@thunderid/nuxt'],
  thunderid: {
    clientId: '<your-client-id>',
    clientSecret: '<your-client-secret>',
    baseUrl: 'https://localhost:8090',
  },
})

Then wrap your root layout with <ThunderIDRoot />:

app.vue

<template>
  <ThunderIDRoot>
    <NuxtPage />
  </ThunderIDRoot>
</template>

For full setup instructions, see the Nuxt quickstart guide.

Features

Configuration

The SDK is configured via the thunderid key in nuxt.config.ts.

• Module Configuration: Full reference for all configuration options

Composables

Auto-imported composables available in every component and page without explicit imports.

• useThunderID(): Access auth state and trigger sign-in, sign-out, and sign-up flows
• useUser(): Access the authenticated user object

Components

All components are auto-registered with the ThunderID prefix and do not require explicit imports.

Provider

• <ThunderIDRoot />: Root provider that mounts all authentication context providers

Control Components

• <ThunderIDSignedIn />: Render content only when the user is authenticated
• <ThunderIDSignedOut />: Render content only when the user is not authenticated
• <ThunderIDLoading />: Render content during authentication loading state

Action Components

• <ThunderIDSignInButton />: Trigger the sign-in flow
• <ThunderIDSignOutButton />: Sign out the current user
• <ThunderIDSignUpButton />: Trigger the sign-up flow

User Self-care Components

• <ThunderIDUser />: Access authenticated user data via slot props
• <ThunderIDUserProfile />: Full profile management interface
• <ThunderIDUserDropdown />: User menu with profile and sign-out options

Middleware

• defineThunderIDMiddleware(): Factory for creating route middleware that gates pages by auth state, organization, or required scopes
• Named 'auth' middleware: pre-built middleware that redirects unauthenticated users to sign-in

Server Utilities

Server-only utilities imported from @thunderid/nuxt/server for use in API routes, server routes, and server middleware.

• useServerSession(): Read the session payload from the current request, or null
• requireServerSession(): Read the session or throw a 401 error
• getValidAccessToken(): Get a valid access token, refreshing it automatically if expired
• get<ProductName />Context(): Read the typed ThunderID context attached to an H3 event

Utilities

• createRouteMatcher(): Build a route-matching function from glob patterns for use in middleware

Error Handling

• ThunderIDError: Structured error class thrown by the SDK with typed ErrorCode values

Built-in API Routes

The module automatically registers the following server routes under /api/auth:

Route	Method	Description
/api/auth/signin	GET	Start redirect-based sign-in
/api/auth/signin	POST	Handle embedded sign-in step
/api/auth/signup	POST	Handle embedded sign-up step
/api/auth/callback	GET / POST	OAuth callback handler
/api/auth/signout	POST	Sign out and return redirect URL
/api/auth/session	GET	Get current auth state
/api/auth/token	GET	Get client-safe access token
/api/auth/user	GET	Get user object
/api/auth/user/profile	GET / PATCH	Get or update user profile
/api/auth/branding	GET	Get tenant branding preference

Package Exports

Export Path	Contents
@thunderid/nuxt	Module, composables, components, middleware, types
@thunderid/nuxt/server	useServerSession, requireServerSession, getValidAccessToken, getThunderIDContext
@thunderid/nuxt/utils	createRouteMatcher
@thunderid/nuxt/errors	ThunderIDError, ErrorCode