NextAuth.js (Auth.js) | Bootspring Docs

Authentication patterns for NextAuth.js v5 (Auth.js) in Next.js applications.

Overview#

NextAuth.js provides flexible authentication with:

Multiple OAuth providers (Google, GitHub, Apple, etc.)
Database adapters for session persistence
JWT or database session strategies
Credentials-based authentication
TypeScript support

Prerequisites:

Next.js 14+ with App Router
Database (optional, for session storage)

Installation#

npm install next-auth @auth/prisma-adapter

# .env.local
AUTH_SECRET=your-secret-key
GITHUB_ID=your-github-client-id
GITHUB_SECRET=your-github-client-secret
GOOGLE_ID=your-google-client-id
GOOGLE_SECRET=your-google-client-secret

Implementation#

Basic Setup#

// auth.ts
import NextAuth from 'next-auth'
import GitHub from 'next-auth/providers/github'
import Google from 'next-auth/providers/google'
import { PrismaAdapter } from '@auth/prisma-adapter'
import { prisma } from '@/lib/db'

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  session: { strategy: 'jwt' },
  providers: [
    GitHub({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!
    }),
    Google({
      clientId: process.env.GOOGLE_ID!,
      clientSecret: process.env.GOOGLE_SECRET!
    })
  ],
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        token.id = user.id
      }
      return token
    },
    async session({ session, token }) {
      if (session.user) {
        session.user.id = token.id as string
      }
      return session
    }
  },
  pages: {
    signIn: '/login',
    error: '/login'
  }
})

Route Handler#

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

export const { GET, POST } = handlers

Server-Side Auth Check#

// lib/auth.ts
import { auth } from '@/auth'

export async function getSession() {
  return auth()
}

export async function requireAuth() {
  const session = await auth()

  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  return session
}

Credentials Provider#

// auth.ts (add to providers)
import Credentials from 'next-auth/providers/credentials'
import bcrypt from 'bcryptjs'

Credentials({
  credentials: {
    email: { type: 'email' },
    password: { type: 'password' }
  },
  async authorize(credentials) {
    const user = await prisma.user.findUnique({
      where: { email: credentials.email as string }
    })

    if (!user?.password) return null

    const valid = await bcrypt.compare(
      credentials.password as string,
      user.password
    )

    if (!valid) return null

    return { id: user.id, email: user.email, name: user.name }
  }
})

// components/auth-buttons.tsx
'use client'
import { signIn, signOut } from 'next-auth/react'
import { Button } from '@/components/ui/button'

export function SignInButton() {
  return (
    <Button onClick={() => signIn('github')}>
      Sign In with GitHub
    </Button>
  )
}

export function SignOutButton() {
  return (
    <Button variant="outline" onClick={() => signOut()}>
      Sign Out
    </Button>
  )
}

Usage Examples#

Protected Server Component#

// app/dashboard/page.tsx
import { auth } from '@/auth'
import { redirect } from 'next/navigation'

export default async function DashboardPage() {
  const session = await auth()

  if (!session) {
    redirect('/login')
  }

  return <Dashboard user={session.user} />
}

Client Component with Session#

// components/user-menu.tsx
'use client'

import { useSession } from 'next-auth/react'

export function UserMenu() {
  const { data: session, status } = useSession()

  if (status === 'loading') {
    return <div>Loading...</div>
  }

  if (!session) {
    return <SignInButton />
  }

  return (
    <div>
      <span>{session.user?.name}</span>
      <SignOutButton />
    </div>
  )
}

Best Practices#

Use JWT strategy for serverless - Database sessions require persistent connections
Always validate in callbacks - Check email verification status
Secure credentials flow - Hash passwords with bcrypt, minimum 12 rounds
Set up session provider - Wrap app in SessionProvider for client access
Use database adapter - For production, persist sessions and accounts

OAuth - OAuth 2.0 integration details
Session Management - Session handling patterns
JWT - JWT token handling