Nuxt

This guide walks you through implementing Aura Auth in a Nuxt application with full support for the Nitro Server Engine. If you haven't configured Aura Auth yet, start with the Installation Guide and Quick Start Guide to set up your Auth instance and environment variables. Then follow the steps in this guide to integrate Aura Auth with your Nuxt application.

Aura Auth is working on developing a Nuxt-specific package that will provide additional utilities and hooks for Nuxt applications. For now, the core package can be used to implement authentication in Nuxt with the patterns outlined in this guide. Stay tuned for updates on the Nuxt package!

Setup Aura Auth

Create an Auth Instance

Create an auth.ts file in shared directory to configure your Aura Auth instance.

shared/auth.ts

import { createAuth } from "@aura-stack/auth"

export const auth = createAuth({
  oauth: ["github"],
  basePath: "/api/auth",
  baseURL: "http://localhost:3000",
})

export const { handlers, jose, api } = auth

The basePath should match the path where your auth route handlers are mounted and baseURL should point to your local development server or deployed application URL.

Create an Auth Client Instance

Create an auth-client.ts file in shared directory to enable client-side features.

shared/auth-client.ts

import { createAuthClient } from "@aura-stack/auth/client"

export const authClient = createAuthClient({
  basePath: "/api/auth",
  baseURL: "http://localhost:3000",
})

The basePath should match the path where your auth route handlers are mounted and baseURL should point to your local development server or deployed application URL. Both options should be the same as the ones used in your auth.ts configuration to ensure client and server instances are aligned.

Mount HTTP Handlers

Create a wildcard catch-all route in server/api/auth/[...aura].ts that delegates to Aura Auth's ALL handler. Nitro's toWebRequest utility ensures handlers.ALL receives a standard Request object.

server/api/auth/[...aura].ts

import { toWebRequest } from "h3"
import { handlers } from "~/shared/auth"

export default defineEventHandler(async (event) => {
  const webRequest = toWebRequest(event)
  return await handlers.ALL(webRequest)
})

Client-Side Rendering (CSR)

With Nuxt, you can use the built-in createAuthClient utility to handle authentication directly from your Vue components.

app.vue

<script setup lang="ts">
import { ref, onMounted } from "vue"
import { authClient } from "~/shared/auth-client"

const session = ref(null)

onMounted(async () => {
  const result = await authClient.getSession()
  session.value = result.session
})

const signIn = () => {
  void authClient.signIn("github")
}

const signOut = async () => {
  await authClient.signOut()
  session.value = null
}
</script>

<template>
  <div>
    <div v-if="session">
      <p>Welcome, {{ session.user?.name }}</p>
      <button @click="signOut">Sign Out</button>
    </div>
    <div v-else>
      <button @click="signIn">Sign in with GitHub</button>
    </div>
  </div>
</template>

This pattern works well for navigation bars, login pages, and other components that only need client-side session state.

Common Pitfalls

Keep basePath aligned with the Nitro route. If the route lives at server/api/auth/[...aura].ts, basePath should stay /api/auth.
Use the shared auth module everywhere. Import shared/auth.ts from the Nitro route and any server-side helpers so there is one auth configuration.
Treat the browser client as optional. Use authClient for interactive UI, but keep the shared server handler in place so session handling stays consistent.