auth-patterns — Claude Code skill: what it does, how to install
auth-patterns is a Claude Code skill for Next.js authentication, covering NextAuth.js v5 setup, middleware route guards, RBAC, and session handling in Server Components.
MIT 183 installs ★ 3,785 updated 2026-10-25
npx skills add davepoon/buildwithclaude --skill auth-patterns -a claude-codeWhat auth-patterns does
This skill guides coding agents through authentication setups in Next.js. It covers NextAuth.js v5 configuration using GitHub and Credentials providers, route handlers under app/api/auth/[...nextauth]/route.ts, and client-side setup with SessionProvider.
It also details custom edge route protection using middleware.ts and the jose library for JWT verification. For role-based access control, the guide provides TypeScript interface extensions, session callback wiring, and an AdminOnly wrapper component.
Database sessions require extra packages like @auth/prisma-adapter, because the basic NextAuth setup in this skill relies on stateless JWT cookies.
What it helps with
- configure NextAuth.js v5 with GitHub and credentials login
- guard dashboard routes and API endpoints using Next.js middleware
- read session data inside React Server Components with auth()
- implement role-based access control with custom session types
Example prompts for the agent
- Show me how to protect
/dashboardroutes using middleware in Next.js - Configure NextAuth.js v5 with GitHub provider and server-side session checks
- How do I add user roles to the Auth.js session and create an AdminOnly wrapper?
How to install auth-patterns
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill auth-patterns -a claude-code2Manually: put the files in place
~/.claude/skills/auth-patterns/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/auth-patterns/
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill auth-patterns -a codex2Manually: put the files in place
.agents/skills/auth-patterns/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill auth-patterns -a cursor2Manually: put the files in place
.cursor/skills/auth-patterns/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install davepoon/buildwithclaude plugins/nextjs-expert/skills/auth-patterns2Manually: put the files in place
.github/skills/auth-patterns/SKILL.md1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill auth-patterns -a gemini-cli2Platform CLI
gemini skills install https://github.com/davepoon/buildwithclaude --path plugins/nextjs-expert/skills/auth-patternsManually: put the files in place
.devin/skills/auth-patterns/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill auth-patterns -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about auth-patterns
How to install auth-patterns in Claude Code?
Run npx skills add davepoon/buildwithclaude --skill auth-patterns -a claude-code in your terminal.
What does auth-patterns do?
It teaches your agent standard patterns for Next.js authentication, covering Auth.js v5, JWT verification in middleware, and session management.
Does auth-patterns support database sessions?
The skill mentions database adapters such as @auth/prisma-adapter, but its default code examples focus on stateless JWT session strategies.
Source text
SKILL.md · MIT
---
name: auth-patterns
description: This skill should be used when the user asks about "authentication in Next.js", "NextAuth", "Auth.js", "middleware auth", "protected routes", "session management", "JWT", "login flow", or needs guidance on implementing authentication and authorization in Next.js applications.
version: 1.0.0
---
# Authentication Patterns in Next.js
## Overview
Next.js supports multiple authentication strategies. This skill covers common patterns including NextAuth.js (Auth.js), middleware-based protection, and session management.
## Authentication Libraries
| Library | Best For |
|---------|----------|
| NextAuth.js (Auth.js) | Full-featured auth with providers |
| Clerk | Managed auth service |
| Lucia | Lightweight, flexible auth |
| Supabase Auth | Supabase ecosystem |
| Custom JWT | Full control |
## NextAuth.js v5 Setup
### Installation
```bash
npm install next-auth@beta
```
### Configuration
```tsx
// auth.ts
import NextAuth from 'next-auth'
import GitHub from 'next-auth/providers/github'
import Credentials from 'next-auth/providers/credentials'
export const { handlers, auth, signIn, signOut } = NextAuth({
providers: [
GitHub({
clientId: process.env.GITHUB_ID,
clientSecret: process.env.GITHUB_SECRET,
}),
Credentials({
credentials: {
email: { label: 'Email', type: 'email' },
password: { label: 'Password', type: 'password' },
},
authorize: async (credentials) => {
const user = await getUserByEmail(credentials.email)
if (!user || !verifyPassword(credentials.password, user.password)) {
return null
}
return user
},
}),
],
callbacks: {
authorized: async ({ auth }) => {
return !!auth
},
},
})
```
### API Route Handler
```tsx
// app/api/auth/[...nextauth]/route.ts
import { handlers } from '@/auth'
export const { GET, POST } = handlers
```
### Middleware Protection
```tsx
// middleware.ts
export { auth as middleware } from '@/auth'
export const config = {
matcher: ['/dashboard/:path*', '/api/protected/:path*'],
}
```
## Getting Session Data
### In Server Components
```tsx
// 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 (
<div>
<h1>Welcome, {session.user?.name}</h1>
</div>
)
}
```
### In Client Components
```tsx
// 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>
)
}
```
### Session Provider Setup
```tsx
// 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>
)
}
```
## Sign In/Out Components
```tsx
// components/auth-buttons.tsx
import { signIn, signOut } from '@/auth'
export function SignInButton() {
return (
<form
action={async () => {
'use server'
await signIn('github')
}}
>
<button type="submit">Sign in with GitHub</button>
</form>
)
}
export function SignOutButton() {
return (
<form
action={async () => {
'use server'
await signOut()
}}
>
<button type="submit">Sign out</button>
</form>
)
}
```
## Middleware-Based Auth
### Basic Pattern
```tsx
// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
const protectedRoutes = ['/dashboard', '/settings', '/api/protected']
const authRoutes = ['/login', '/signup']
export function middleware(request: NextRequest) {
const token = request.cookies.get('session')?.value
const { pathname } = request.nextUrl
// Redirect authenticated users away from auth pages
if (authRoutes.some(route => pathname.startsWith(route))) {
if (token) {
return NextResponse.redirect(new URL('/dashboard', request.url))
}
return NextResponse.next()
}
// Protect routes
if (protectedRoutes.some(route => pathname.startsWith(route))) {
if (!token) {
const loginUrl = new URL('/login', request.url)
loginUrl.searchParams.set('callbackUrl', pathname)
return NextResponse.redirect(loginUrl)
}
}
return NextResponse.next()
}
export const config = {
matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}
```
### With JWT Verification
```tsx
// middleware.ts
import { NextResponse } from 'next/server'
import { jwtVerify } from 'jose'
const secret = new TextEncoder().encode(process.env.JWT_SECRET)
export async function middleware(request: NextRequest) {
const token = request.cookies.get('token')?.value
if (!token) {
return NextResponse.redirect(new URL('/login', request.url))
}
try {
const { payload } = await jwtVerify(token, secret)
// Token is valid, continue
return NextResponse.next()
} catch {
// Token is invalid
return NextResponse.redirect(new URL('/login', request.url))
}
}
```
## Role-Based Access Control
### Extending Session Types
```tsx
// types/next-auth.d.ts
import { DefaultSession } from 'next-auth'
declare module 'next-auth' {
interface Session {
user: {
role: 'user' | 'admin'
} & DefaultSession['user']
}
}
// auth.ts
export const { handlers, auth } = NextAuth({
callbacks: {
session: ({ session, token }) => ({
...session,
user: {
...session.user,
role: token.role,
},
}),
jwt: ({ token, user }) => {
if (user) {
token.role = user.role
}
return token
},
},
})
```
### Role-Based Component
```tsx
// components/admin-only.tsx
import { auth } from '@/auth'
import { redirect } from 'next/navigation'
export async function AdminOnly({ children }: { children: React.ReactNode }) {
const session = await auth()
if (session?.user?.role !== 'admin') {
redirect('/unauthorized')
}
return <>{children}</>
}
// Usage
export default async function AdminPage() {
return (
<AdminOnly>
<AdminDashboard />
</AdminOnly>
)
}
```
## Session Storage Options
### JWT (Stateless)
```tsx
// auth.ts
export const { auth } = NextAuth({
session: { strategy: 'jwt' },
// JWT stored in cookies, no database needed
})
```
### Database Sessions
```tsx
// auth.ts
import { PrismaAdapter } from '@auth/prisma-adapter'
import { prisma } from '@/lib/prisma'
export const { auth } = NextAuth({
adapter: PrismaAdapter(prisma),
session: { strategy: 'database' },
// Sessions stored in database
})
```
## Custom Login Page
```tsx
// app/login/page.tsx
'use client'
import { signIn } from 'next-auth/react'
import { useSearchParams } from 'next/navigation'
export default function LoginPage() {
const searchParams = useSearchParams()
const callbackUrl = searchParams.get('callbackUrl') || '/dashboard'
return (
<div className="flex flex-col gap-4">
<button
onClick={() => signIn('github', { callbackUrl })}
className="btn"
>
Sign in with GitHub
</button>
<button
onClick={() => signIn('google', { callbackUrl })}
className="btn"
>
Sign in with Google
</button>
</div>
)
}
```
## Security Best Practices
1. **Use HTTPS** in production
2. **Set secure cookie flags** (HttpOnly, Secure, SameSite)
3. **Implement CSRF protection** (built into NextAuth)
4. **Validate redirect URLs** to prevent open redirects
5. **Use environment variables** for secrets
6. **Implement rate limiting** on auth endpoints
7. **Hash passwords** with bcrypt or argon2
## Resources
For detailed patterns, see:
- `references/middleware-auth.md` - Advanced middleware patterns
- `references/session-management.md` - Session strategies
- `examples/nextauth-setup.md` - Complete NextAuth.js setup
© davepoon · MIT · davepoon/buildwithclaude