Skill

nextjs-auth

Implements NextAuth.js/Auth.js authentication in Next.js apps with providers, callbacks, server sessions, type extensions, and protected routes.

Next.js

Typescript

authentication

npx claudepluginhub bradtaylorsf/alphaagent-team

Configuration

User-invocable: No — Claude only

Tool Access

This skill uses the workspace's default tool permissions.

Preview

Patterns for implementing authentication with NextAuth.js / Auth.js.

SKILL.md

Similar Skills

cache-components

139.4k

Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.

cache-components

pdf

131.6k

Processes PDFs: extracts text/tables/images, merges/splits/rotates pages, adds watermarks, creates/fills forms, encrypts/decrypts, OCRs scans. Activates on PDF mentions or output requests.

11 files

document-skills

Stats

Parent Repo Stars8

Parent Repo Forks2

Last CommitJan 25, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

Next.js Auth Skill

Patterns for implementing authentication with NextAuth.js / Auth.js.

Setup

Basic Configuration

// app/api/auth/[...nextauth]/route.ts
import NextAuth from 'next-auth'
import { authOptions } from '@/lib/auth'

const handler = NextAuth(authOptions)
export { handler as GET, handler as POST }

// lib/auth.ts
import { NextAuthOptions } from 'next-auth'
import CredentialsProvider from 'next-auth/providers/credentials'
import GoogleProvider from 'next-auth/providers/google'

export const authOptions: NextAuthOptions = {
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
    CredentialsProvider({
      name: 'Credentials',
      credentials: {
        email: { label: 'Email', type: 'email' },
        password: { label: 'Password', type: 'password' },
      },
      async authorize(credentials) {
        const user = await verifyCredentials(
          credentials?.email,
          credentials?.password
        )
        if (user) return user
        return null
      },
    }),
  ],
  pages: {
    signIn: '/auth/signin',
    signOut: '/auth/signout',
    error: '/auth/error',
  },
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        token.id = user.id
        token.role = user.role
      }
      return token
    },
    async session({ session, token }) {
      session.user.id = token.id as string
      session.user.role = token.role as string
      return session
    },
  },
  session: {
    strategy: 'jwt',
  },
}

Type Extensions

// types/next-auth.d.ts
import { DefaultSession } from 'next-auth'

declare module 'next-auth' {
  interface Session {
    user: {
      id: string
      role: string
    } & DefaultSession['user']
  }

  interface User {
    role: string
  }
}

declare module 'next-auth/jwt' {
  interface JWT {
    id: string
    role: string
  }
}

Server-Side Auth

Getting Session in Server Components

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

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

  if (!session) {
    redirect('/auth/signin')
  }

  return (
    <div>
      <h1>Welcome, {session.user.name}</h1>
      <p>Role: {session.user.role}</p>
    </div>
  )
}

Auth in API Routes

// app/api/protected/route.ts
import { getServerSession } from 'next-auth'
import { authOptions } from '@/lib/auth'
import { NextResponse } from 'next/server'

export async function GET() {
  const session = await getServerSession(authOptions)

  if (!session) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    )
  }

  // User is authenticated
  return NextResponse.json({
    user: session.user,
    data: await getProtectedData(session.user.id),
  })
}

Client-Side Auth

Session Provider

// app/providers.tsx
'use client'

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

export function Providers({ children }: { children: React.ReactNode }) {
  return <SessionProvider>{children}</SessionProvider>
}

// app/layout.tsx
import { Providers } from './providers'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

useSession Hook

'use client'

import { useSession, signIn, signOut } from 'next-auth/react'

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

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

  if (session) {
    return (
      <div>
        <span>Welcome, {session.user.name}</span>
        <button onClick={() => signOut()}>Sign Out</button>
      </div>
    )
  }

  return <button onClick={() => signIn()}>Sign In</button>
}

Protected Client Component

'use client'

import { useSession } from 'next-auth/react'
import { useRouter } from 'next/navigation'
import { useEffect } from 'react'

export function ProtectedComponent({ children }: { children: React.ReactNode }) {
  const { status } = useSession()
  const router = useRouter()

  useEffect(() => {
    if (status === 'unauthenticated') {
      router.push('/auth/signin')
    }
  }, [status, router])

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

  if (status === 'authenticated') {
    return <>{children}</>
  }

  return null
}

Middleware Protection

// middleware.ts
import { withAuth } from 'next-auth/middleware'
import { NextResponse } from 'next/server'

export default withAuth(
  function middleware(req) {
    const token = req.nextauth.token
    const path = req.nextUrl.pathname

    // Role-based access control
    if (path.startsWith('/admin') && token?.role !== 'admin') {
      return NextResponse.redirect(new URL('/unauthorized', req.url))
    }

    return NextResponse.next()
  },
  {
    callbacks: {
      authorized: ({ token }) => !!token,
    },
  }
)

export const config = {
  matcher: ['/dashboard/:path*', '/admin/:path*', '/account/:path*'],
}

Custom Sign In Page

// app/auth/signin/page.tsx
'use client'

import { signIn } from 'next-auth/react'
import { useSearchParams } from 'next/navigation'
import { useState } from 'react'

export default function SignIn() {
  const searchParams = useSearchParams()
  const callbackUrl = searchParams.get('callbackUrl') || '/dashboard'
  const error = searchParams.get('error')

  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()
    await signIn('credentials', {
      email,
      password,
      callbackUrl,
    })
  }

  return (
    <div className="signin-page">
      <h1>Sign In</h1>

      {error && <div className="error">Authentication failed</div>}

      <form onSubmit={handleSubmit}>
        <input
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          placeholder="Email"
        />
        <input
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          placeholder="Password"
        />
        <button type="submit">Sign In</button>
      </form>

      <div className="divider">or</div>

      <button onClick={() => signIn('google', { callbackUrl })}>
        Sign in with Google
      </button>
    </div>
  )
}

Database Sessions

// lib/auth.ts
import { PrismaAdapter } from '@auth/prisma-adapter'
import { prisma } from '@/lib/prisma'

export const authOptions: NextAuthOptions = {
  adapter: PrismaAdapter(prisma),
  session: {
    strategy: 'database',  // Store sessions in database
  },
  providers: [...],
  callbacks: {
    async session({ session, user }) {
      session.user.id = user.id
      session.user.role = user.role
      return session
    },
  },
}

Callbacks

JWT Callback

callbacks: {
  async jwt({ token, user, account, trigger, session }) {
    // Initial sign in
    if (user) {
      token.id = user.id
      token.role = user.role
    }

    // Update triggered from client
    if (trigger === 'update' && session) {
      token.name = session.name
    }

    // Refresh token
    if (account?.provider === 'google') {
      token.accessToken = account.access_token
    }

    return token
  },
}

Session Callback

callbacks: {
  async session({ session, token, user }) {
    // JWT strategy
    if (token) {
      session.user.id = token.id
      session.user.role = token.role
    }

    // Database strategy
    if (user) {
      session.user.id = user.id
      session.user.role = user.role
    }

    return session
  },
}

Sign In Callback

callbacks: {
  async signIn({ user, account, profile }) {
    // Block certain emails
    if (user.email?.endsWith('@blocked.com')) {
      return false
    }

    // Allow OAuth but verify email for credentials
    if (account?.provider === 'credentials') {
      const dbUser = await prisma.user.findUnique({
        where: { email: user.email },
      })
      if (!dbUser?.emailVerified) {
        return '/auth/verify-email'  // Redirect
      }
    }

    return true
  },
}

Events

events: {
  async signIn({ user, account, isNewUser }) {
    if (isNewUser) {
      await sendWelcomeEmail(user.email)
    }
    await logSignIn(user.id, account?.provider)
  },

  async signOut({ token }) {
    await logSignOut(token.id)
  },

  async createUser({ user }) {
    await initializeUserDefaults(user.id)
  },
}

Integration

Used by:

frontend-developer agent
backend-developer agent
fullstack-developer agent