/api-auth-nextauth

name: api-auth-nextauth
description: Auth.js (NextAuth v5) authentication patterns - configuration, providers, session strategies, middleware, database adapters, role-based access, Edge compatibility

Auth.js (NextAuth v5) Patterns

> **Quick Guide:** Configure Auth.js in a root `auth.ts` file exporting `{ auth, handlers, signIn, signOut }` from `NextAuth()`. Use the unified `auth()` function everywhere (Server Components, Route Handlers, middleware). Default session strategy is JWT (cookie-based); add a database adapter for persistent sessions. Protect routes via middleware or per-page `auth()` checks.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST configure Auth.js in a root `auth.ts` file and export `{ auth, handlers, signIn, signOut }` from `NextAuth()`)**

**(You MUST use the unified `auth()` function for server-side session access - NOT the deprecated `getServerSession()`, `getSession()`, or `getToken()`)**

**(You MUST use `AUTH_SECRET` environment variable - `NEXTAUTH_SECRET` is deprecated in v5)**

**(You MUST use `AUTH_` prefixed environment variables for provider credentials (e.g., `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`) - they are auto-detected)**

**(You MUST split auth config into `auth.config.ts` (Edge-compatible) and `auth.ts` (with adapter) when using database sessions with middleware)**

**(You MUST check session inside Server Actions and API routes - middleware alone is NOT sufficient for authorization)**

</critical_requirements>

---

**Auto-detection:** Auth.js, NextAuth, next-auth, authjs, auth.ts, auth.config.ts, NextAuth(), signIn, signOut, auth(), handlers, SessionProvider, useSession, AUTH_SECRET, OAuth provider, credentials provider, database adapter, @auth/prisma-adapter, @auth/drizzle-adapter, authorized callback, jwt callback, session callback, proxy auth, middleware auth

**When to use:**

• Adding authentication to Next.js, SvelteKit, Express, or Qwik apps
• Implementing OAuth login (GitHub, Google, Discord, etc.) with 80+ built-in providers
• Building email/magic link authentication flows
• Need JWT or database-backed session management
• Projects requiring Edge-compatible middleware authentication

**When NOT to use:**

• Building a custom auth system from scratch (Auth.js is opinionated)
• Need fine-grained organization/team management out of the box
• Mobile-only apps without web frontend
• Need self-hosted auth with plugin architecture

**Key patterns covered:**

• Auth configuration (`auth.ts`, `auth.config.ts`)
• OAuth providers (GitHub, Google, Credentials, Email)
• Session strategies (JWT vs database)
• Session access (Server Components, Route Handlers, Client Components)
• Middleware/proxy route protection
• Database adapters (Prisma, Drizzle)
• Callbacks (jwt, session, signIn, redirect)
• Role-based access control
• Edge compatibility split configuration

**Detailed Resources:**

• For decision frameworks and anti-patterns, see [reference.md](reference.md)

**Core patterns:**

• [examples/core.md](examples/core.md) - Auth configuration, providers, callbacks
• [examples/session.md](examples/session.md) - Session strategies, session access patterns
• [examples/middleware.md](examples/middleware.md) - Route protection, middleware, Edge compatibility
• [examples/database.md](examples/database.md) - Database adapters, Prisma, Drizzle
• [examples/patterns.md](examples/patterns.md) - Role-based access, magic links, account linking

---

<philosophy>

Philosophy

Auth.js (v5) consolidates authentication into a **single, unified API**. The `auth()` function replaces `getServerSession`, `getSession`, `withAuth`, and `getToken` from v4 for server-side use. `useSession()` remains the correct client-side API. Configuration lives in a root file, not in API routes.

**Core principles:**

1. **Framework-agnostic** - Works with Next.js, SvelteKit, Express, Qwik 2. **Unified API** - Single `auth()` function for all server-side contexts 3. **Provider ecosystem** - 80+ built-in OAuth providers with auto-detection of `AUTH_*` env vars 4. **JWT by default** - Stateless sessions in encrypted cookies, no database required 5. **Edge-compatible** - Middleware runs on Edge runtime with split configuration (Next.js 16 proxy runs on Node.js) 6. **Progressive complexity** - Start with OAuth, add database adapter, then customize callbacks

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Auth Configuration

The central configuration file exports everything you need from `NextAuth()`.

Basic OAuth Setup

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [
    GitHub, // Auto-detects AUTH_GITHUB_ID and AUTH_GITHUB_SECRET
    Google, // Auto-detects AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET
  ],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";

export const { GET, POST } = handlers;

**Why good:** Single config file exports all auth utilities, providers auto-detect `AUTH_*` env vars, API route is minimal

Environment Variables

# .env.local
AUTH_SECRET="generate-with-npx-auth-secret"  # Required
AUTH_GITHUB_ID="your-github-client-id"       # Auto-detected by GitHub provider
AUTH_GITHUB_SECRET="your-github-secret"      # Auto-detected by GitHub provider
AUTH_GOOGLE_ID="your-google-id"       # Auto-detected by Google provider
AUTH_GOOGLE_SECRET="your-google-secret"

**Why good:** `AUTH_` prefix is standardized in v5, `AUTH_SECRET` replaces deprecated `NEXTAUTH_SECRET`, providers auto-detect credentials

---

Pattern 2: Providers

Auth.js supports OAuth, email/magic link, and credentials authentication. 80+ built-in OAuth providers auto-detect `AUTH_*` env vars.

// OAuth: customize profile mapping
GitHub({
  profile(profile) {
    return {
      id: Strin