Aura Auth adapter and utilities for the Next.js ecosystem

Official Docs · Next.js Package Docs

Overview

@aura-stack/next provides a high-level, type-safe integration for Next.js applications using Aura Auth. It is designed for maximum developer experience in the App Router, offering dedicated utilities for Server Components, Server Actions, Middleware, and Route Handlers.

By utilizing a "Concentrated API" pattern, it optimizes core authentication logic for the Next.js runtime, automatically managing context-aware data like cookies and headers via next/headers.

Features

• App Router Optimized — Full support for React Server Components (RSC) and Server Actions.
• Concentrated API — Dedicated auth.api for Next.js that automates session fetching and redirects.
• Aggregated Client Entry — Consolidated import { ... } from "@aura-stack/next/client" for all hooks and context.
• Type-safe by design — Automatic type inference from your identity schema.

Installation

pnpm add @aura-stack/next

[!NOTE] Ensure you have react (>= 19.x) installed.

Quick Start

1. Create Auth Instance

Configure your auth instance in a shared file (e.g., lib/auth.ts).

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

export const auth = createAuth({
  oauth: ["github"],
})

export const { api, core } = auth

2. Set Up Route Handler

Configure the catch-all route in app/api/auth/[...auth]/route.ts.

import { core } from "@/lib/auth"

export const { GET, POST, PATCH } = core.handlers

3. Access Session (Server-side)

Use the optimized API in your Server Components.

import { api } from "@/lib/auth"

export default async function Page() {
  const session = await api.getSession()

  if (!session) return <div>Not signed in</div>

  return <div>Welcome, {session.user.name}</div>
}

4. Configure Auth Client Instance and Auth Provider

Wrap your application with the AuthProvider and pass it a configured Aura Auth client.

import { createAuthClient, AuthProvider } from "@aura-stack/next/client"
import type { PropsWithChildren } from "react"

const client = createAuthClient({
  /* your config */
})

export const App = ({ children }: PropsWithChildren) => {
  return <AuthProvider client={client}>{children}</AuthProvider>
}

5. Client-side Implementation

Use the consolidated client entry for hooks and context.

"use client"
import { useSession } from "@aura-stack/next/client"

export function Profile() {
  const { session, status } = useSession()
  if (status === "loading") return <p>Loading...</p>

  return (
    <div>
      <p>Welcome, {session.user.name}!</p>
    </div>
  )
}

Documentation

Visit the official documentation website.

License

Licensed under the MIT License. © Aura Stack