Skip to Content

Nuxt Quickstart 💚

Add a complete login experience to a Nuxt 3 app. @faable/auth-js drives the Authorization Code flow with PKCE, stores the session, refreshes tokens, and syncs across tabs.

The one thing to get right in Nuxt: the SDK is client-only. It uses window, localStorage, and PKCE, so it can’t run during server-side rendering. You create it in a client plugin (plugins/faable.client.ts — the .client suffix makes Nuxt run it only in the browser) and expose the session through a useState-backed composable so it survives hydration.

This is still the framework-agnostic core pattern — createClient + onAuthStateChange + getSession — wired into Nuxt’s SSR-safe state. The Vue, JavaScript, SvelteKit, and Angular quickstarts are the same three calls in each framework.

You need one package: @faable/auth-js — Nuxt uses the core client directly, no framework helper required.


✅ Prerequisites

In the Faable Dashboard , create a Client for your app and configure:

  • Allowed Callback URLs: http://localhost:3000/callback (add your production URL later).
  • Allowed Logout URLs: http://localhost:3000.
  • Allowed Web Origins: http://localhost:3000.

Note your auth domain (your-domain.auth.faable.link) and Client ID. Browser apps are public clients — no client secret is involved.


🛠️ Step 1: Create the App and Install

npm create nuxt@latest my-app # or: npx nuxi init my-app cd my-app npm install @faable/auth-js

Step 2: Create the Client in a Client Plugin

The SDK touches window and PKCE storage, so it must never run on the server. A plugin named *.client.ts runs only in the browser — exactly where you want it. Create the client there and provide it to the rest of the app via nuxtApp.provide.

// plugins/faable.client.ts import { createClient } from '@faable/auth-js' export default defineNuxtPlugin(() => { const auth = createClient({ domain: 'your-domain.auth.faable.link', clientId: 'YOUR_CLIENT_ID', redirectUri: window.location.origin + '/callback' }) return { provide: { auth } } })

provide: { auth } exposes the client as useNuxtApp().$auth everywhere in the app. On creation the client recovers an existing session from storage, or — on the callback URL — exchanges the PKCE ?code= for tokens.

Step 3: Wire a Reactive Session Composable

Wrap the client in a useAuth() composable. It holds the session in Nuxt’s useState — SSR-safe shared state that survives hydration — seeds it once with getSession(), and keeps it updated with onAuthStateChange on login, logout, token refresh, or a change in another tab. All of that runs client-side, guarded by import.meta.client.

// composables/useAuth.ts import type { Session } from '@faable/auth-js' export function useAuth() { const { $auth } = useNuxtApp() const session = useState<Session | null>('faable-session', () => null) // Only the browser has $auth (client plugin) and window. if (import.meta.client && $auth) { // Keep state in sync with every auth change (login, refresh, logout, other tabs). $auth.onAuthStateChange((_event, next) => { session.value = next }) // Seed the initial value once (also auto-refreshes an expired session). $auth.getSession().then(({ data }) => { session.value = data.session }) } return { auth: $auth, session, user: computed(() => session.value?.user ?? null), signIn: () => $auth?.signIn(), signOut: () => $auth?.signOut({ scope: 'global', returnTo: window.location.origin }) } }

onAuthStateChange returns { data: { subscription } }; call subscription.unsubscribe() if you ever need to tear the listener down. Here it lives for the app’s lifetime, so we let it run.

Step 4: Login, User, and Logout

Any page or component reads the composable. Because sign-in state only exists in the browser, wrap the auth UI in <ClientOnly> — it renders nothing on the server and mounts the real UI after hydration, so there’s no flash of the wrong state.

<!-- app.vue --> <script setup lang="ts"> const { session, user, signIn, signOut } = useAuth(); </script> <template> <ClientOnly> <button v-if="!session" @click="signIn">Sign in</button> <div v-else> <p>Hello {{ user?.email }}</p> <button @click="signOut">Sign out</button> </div> <template #fallback> <p>Loading…</p> </template> </ClientOnly> </template>
  • signIn() sends the user to your tenant’s Universal Login with every connection you’ve enabled. Target one directly with signInWithOauthConnection({ connection_id: "connection_..." }).
  • signOut({ scope: 'global', returnTo }) clears the local session and the SSO cookie on the auth server, so the user is signed out of every app on your tenant. signOut() alone signs out of this app only: it revokes this app’s refresh token and stays on the page. returnTo must be in Allowed Logout URLs.
  • Both methods redirect the browser on success — the promise intentionally never resolves, so don’t put code after the await. The UI updates through the composable’s useState, not a return value.

Step 5: The Callback Page

Add a /callback page that finishes the exchange, then navigates home. Run handleRedirectCallback() in onMounted so it only fires in the browser. It’s idempotent — the client already started the exchange on creation — and returns { error, returnTo }, so deep links survive the login round-trip if you passed returnTo to signInWithOauthConnection({ returnTo }).

<!-- pages/callback.vue --> <script setup lang="ts"> const { $auth } = useNuxtApp(); const message = ref("Signing you in…"); onMounted(async () => { const { error, returnTo } = await $auth.handleRedirectCallback(); if (error) message.value = error.message; else navigateTo(returnTo ?? "/"); }); </script> <template> <p>{{ message }}</p> </template>

Nuxt’s file-based router serves this at /callback automatically — the same path you registered as your Allowed Callback URL. onMounted never runs during SSR, so the SDK stays client-only.

Step 6: Call Your API

The access token lives on the session. Read it fresh before each call — getSession() auto-refreshes an expired session:

// composables/apiFetch.ts export async function apiFetch(path: string) { const { $auth } = useNuxtApp() const { data, error } = await $auth.getSession() if (error || !data.session) throw new Error('Not signed in') return fetch(`https://api.myapp.com${path}`, { headers: { authorization: `Bearer ${data.session.access_token}` } }) }

If your backend validates the token’s audience, pass your API identifier when creating the client (createClient({ ..., audience: "https://api.myapp.com" })) — and see Validate Access Tokens for the Express middleware on the other side.


❓ FAQ

Why a client plugin instead of a normal plugin?

@faable/auth-js uses window, localStorage, and PKCE, none of which exist during Nuxt’s server-side render. A plugin named faable.client.ts runs only in the browser — the .client suffix is Nuxt’s built-in signal. Create the client there and provide it, and it never executes on the server. Guard any composable logic with import.meta.client for the same reason.

How do I keep the session reactive without it breaking hydration?

Hold it in useState<Session | null>("faable-session", () => null) — Nuxt’s SSR-safe shared state — update it from onAuthStateChange, and seed it once with getSession() (Step 3). Every component that calls useAuth() shares the same state, and wrapping auth UI in <ClientOnly> avoids a server/client mismatch since the real session only exists in the browser.

How do I get the access token in Nuxt?

From the session: const { data } = await $auth.getSession(), then data.session?.access_token. There is no separate getAccessToken() — getSession() already refreshes expired tokens before returning. Read it fresh right before each API call, as in Step 6.

How do I send users straight to one provider?

Pass connection_id to signInWithOauthConnection — e.g. signIn: () => $auth.signInWithOauthConnection({ connection_id: "connection_..." }). Find the ID in Dashboard → Auth → Connections. Without it, users pick on the Universal Login screen.

Why doesn’t the sign-in promise resolve?

signIn and signOut({ scope: 'global' }) redirect the browser on success, so the page unloads before the promise settles. Let the composable’s useState drive your UI through onAuthStateChange — don’t put post-login logic after the await.


Last updated on