Auth.js v5 Authentication Stack

Production-tested: Multiple Next.js and Cloudflare Workers projects Last Updated: 2025-10-26 Status: Production Ready ✅ Official Docs: https://authjs.dev

---

⚠️ BEFORE YOU START (READ THIS!)

CRITICAL FOR AI AGENTS: If you're Claude Code helping a user set up Auth.js:

1. Explicitly state you're using this skill at the start of the conversation
2. Reference patterns from the skill rather than general knowledge
3. Prevent known issues listed in references/common-errors.md
4. Don't guess - if unsure, check the skill documentation

USER ACTION REQUIRED: Tell Claude to check this skill first!

Say: "I'm setting up Auth.js - check the auth-js skill first"

Why This Matters (Real-World Results)

Without skill activation:

• ❌ Setup time: ~15 minutes
• ❌ Errors encountered: 3-5 (AUTH_SECRET, CallbackRouteError, edge issues)
• ❌ Manual fixes needed: 3-4 commits
• ❌ Token usage: ~15k
• ❌ User confidence: Multiple debugging sessions

With skill activation:

• ✅ Setup time: ~3 minutes
• ✅ Errors encountered: 0
• ✅ Manual fixes needed: 0
• ✅ Token usage: ~6k (60% reduction)
• ✅ User confidence: Instant success

Known Issues This Skill Prevents

1. Missing AUTH_SECRET → JWEDecryptionFailed error
2. CallbackRouteError → Throwing in authorize() instead of returning null
3. Route not found → Incorrect file path for [...nextauth].js
4. Edge incompatibility → Using database session without edge-compatible adapter
5. PKCE errors → OAuth provider misconfiguration
6. Session not updating → Missing middleware
7. v5 migration issues → Namespace changes, JWT salt changes
8. D1 binding errors → Wrangler configuration mismatch
9. Credentials with database → Incompatible session strategy
10. Production deployment failures → Missing environment variables
11. Token refresh errors → Incorrect callback implementation
12. JSON expected but HTML received → Rewrites configuration in Next.js 15

All of these are handled automatically when the skill is active.

---

Table of Contents

1. Quick Start - Next.js
2. Quick Start - Cloudflare Workers
3. Core Concepts
4. Session Strategies
5. Provider Setup
6. Database Adapters
7. Middleware Patterns
8. Advanced Features
9. Critical Rules
10. Common Errors & Fixes
11. Templates Reference

---

Quick Start: Next.js

Prerequisites

# Next.js 15+ with App Router
npm create next-app@latest my-app
cd my-app

Installation

npm install next-auth@latest
npm install @auth/core@latest

# Choose your database adapter (if using database sessions)
npm install @auth/prisma-adapter  # For PostgreSQL/MySQL
npm install @auth/d1-adapter      # For Cloudflare D1

1. Create Auth Configuration

Option A: Simple Setup (JWT sessions, no database)

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

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    GitHub({
      clientId: process.env.AUTH_GITHUB_ID,
      clientSecret: process.env.AUTH_GITHUB_SECRET,
    }),
  ],
})

Option B: Edge-Compatible Setup (recommended for middleware)

// auth.config.ts (edge-compatible, no database)
import type { NextAuthConfig } from "next-auth"
import GitHub from "next-auth/providers/github"

export default {
  providers: [
    GitHub({
      clientId: process.env.AUTH_GITHUB_ID,
      clientSecret: process.env.AUTH_GITHUB_SECRET,
    }),
  ],
} satisfies NextAuthConfig

// auth.ts (full config with database)
import NextAuth from "next-auth"
import { PrismaAdapter } from "@auth/prisma-adapter"
import { PrismaClient } from "@prisma/client"
import authConfig from "./auth.config"

const prisma = new PrismaClient()

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  session: { strategy: "jwt" }, // CRITICAL: Force JWT for edge compatibility
  ...authConfig,
})

2. Create API Route Handler

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

export const { GET, POST } = handlers

3. Add Middleware (Optional but Recommended)

// middleware.ts
export { auth as middleware } from "@/auth"

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
}

4. Environment Variables

# .env.local
AUTH_SECRET=your-secret-here  # Generate with: npx auth secret
AUTH_GITHUB_ID=your_github_client_id
AUTH_GITHUB_SECRET=your_github_client_secret

# CRITICAL: In production, AUTH_SECRET is REQUIRED

5. Use in Components

**Server Component (

...