Nuxt Quickstart
Use this guide to add ThunderID authentication to a Nuxt 3 application using the @thunderid/nuxt module.
What You Will Learn
- Create a new Nuxt 3 app
- Register the
@thunderid/nuxtmodule
- Add working sign-in and sign-out
- Wrap your app with ThunderIDRoot
Prerequisites
- About 15 minutes
- Node.js 18.0 or later installed on your system
- npm, yarn, or pnpm
- Your preferred code editor
Run ThunderID
Start a local ThunderID instance. Pick the method that works best for you:
Requires Node.js 18+
Full install guide →Once it's running, the console is available at https://localhost:8090/console.
Create an Application
-
Sign in to the Console.
Test UserIf you used the default setup, sign in to the Console as
adminwith the password generated during setup and printed to the setup output (unless you supplied your own). -
Navigate to Applications, and click Add Application.
-
Under Technology, select Nuxt.
-
Enter a name (e.g.
My Nuxt App) and create an application. The rest of the settings can stay at their defaults. -
Copy both the Client ID and Client Secret from the window that pops up. The Client ID can also be found in the General tab.
-
Under General, add
http://localhost:3000/api/auth/callbackto the list of Authorized Redirect URIs.
Create a Nuxt App
Create a new Nuxt 3 app:
npm
pnpm
Yarn
npm create nuxt@latest my-nuxt-app
cd my-nuxt-app
pnpm create nuxt@latest my-nuxt-app
cd my-nuxt-app
yarn create nuxt my-nuxt-app
cd my-nuxt-app
Install @thunderid/nuxt
Install the ThunderID Nuxt module:
- npm
- pnpm
- Yarn
Bun
npm install @thunderid/nuxt
pnpm add @thunderid/nuxt
yarn add @thunderid/nuxt
bun add @thunderid/nuxt
Register the Module
Add @thunderid/nuxt to your nuxt.config.ts:
// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
compatibilityDate: '2025-07-15',
devtools: { enabled: true },
modules: ['@thunderid/nuxt'],
})
That's all the nuxt.config.ts change needed. The module reads all configuration from environment variables.
The module automatically registers /api/auth/callback as a Nitro server route. Make sure the authorized redirect URL in your ThunderID application settings is set to http://localhost:3000/api/auth/callback. You do not need to create the callback route yourself.
Set Environment Variables
Create a .env file in your project root with the following:
Replace <your-client-id> and <your-client-secret> with the values from your ThunderID application.
Generate a random string for THUNDERID_SESSION_SECRET (at least 32 characters):
openssl rand -base64 32
NUXT_PUBLIC_THUNDERID_BASE_URL=https://localhost:8090
NUXT_PUBLIC_THUNDERID_CLIENT_ID=<your-client-id>
THUNDERID_CLIENT_SECRET=<your-client-secret>
THUNDERID_SESSION_SECRET=<a-random-secret-for-session-signing>
# DANGER: Disables ALL TLS verification. Only for local development with self-signed certs. NEVER use in production.
NODE_TLS_REJECT_UNAUTHORIZED=0
Wrap Your App with ThunderIDRoot
The <ThunderIDRoot> component mounts the full authentication provider tree. Wrap your application content with it in app.vue:
<template>
<ThunderIDRoot>
<NuxtPage />
</ThunderIDRoot>
</template>
The @thunderid/nuxt module auto-registers all components and auto-imports all composables. You do not need to import them manually.
Build with ThunderID Components
Update your home page with ThunderID authentication components:
<template>
<main>
<SignedIn>
<UserDropdown />
</SignedIn>
<SignedOut>
<SignInButton>Sign In</SignInButton>
</SignedOut>
</main>
</template>
Run Your App
Start the development server:
- npm
- pnpm
- Yarn
npm run dev
pnpm run dev
yarn dev
You'll need a user to sign in with. If you haven't created one yet, open https://localhost:8090/console, navigate to Users, and add a test user with an email and password.
Visit your app at 🌐 http://localhost:3000
You should see the <SignInButton /> button. Click it to be redirected to the ThunderID-hosted sign-in page. Login with your test user, then return to your app with the user dropdown displayed.
