/add-auth

You are adding authentication to a Next.js application using Auth.js (NextAuth.js v5).

Workflow

Step 1: Assess Current State

1. Check if authentication already exists:

   • Look for auth.ts or auth.config.ts
   • Check for next-auth in package.json
   • Look for existing middleware

2. Identify database setup:

   • Check for Prisma schema
   • Identify existing User model

Step 2: Ask About Requirements

Use AskUserQuestion to clarify:

• Providers: Which OAuth providers? (GitHub, Google, Email/Password)
• Session strategy: JWT or database sessions?
• Protected routes: Which routes need protection?
• Role-based access: Is RBAC needed?

Step 3: Install Dependencies

npm install next-auth@beta @auth/prisma-adapter

If using credentials:

npm install bcryptjs
npm install -D @types/bcryptjs

Step 4: Create Auth Configuration

Apply the auth-patterns skill and create:

1. auth.ts - Main auth configuration with:

   • Provider setup
   • Adapter configuration
   • Session callbacks
   • JWT callbacks

2. app/api/auth/[...nextauth]/route.ts - Route handler

Step 5: Add Middleware

Create middleware.ts with:

• Route protection logic
• Redirect rules for auth pages
• Public route exceptions

Step 6: Update Database Schema

If using Prisma, add/update models:

• User
• Account
• Session
• VerificationToken

Step 7: Create Auth Components

1. Login form - Credentials + OAuth buttons
2. Register form - If using credentials
3. User menu - Session-aware navigation
4. Session provider - Client-side wrapper

Step 8: Environment Variables

Create/update .env.local:

AUTH_SECRET=generated-secret
AUTH_URL=http://localhost:3000
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Implementation Checklist

• Install next-auth@beta
• Create auth.ts configuration
• Create API route handler
• Add middleware for route protection
• Update Prisma schema (if using database)
• Create login/register pages
• Add SessionProvider to layout
• Create auth-related components
• Set up environment variables
• Test authentication flow

Files to Create

File	Purpose
auth.ts	Auth configuration
app/api/auth/[...nextauth]/route.ts	NextAuth route handler
middleware.ts	Route protection
app/login/page.tsx	Login page
app/register/page.tsx	Registration page (if credentials)
components/login-form.tsx	Login form component
components/oauth-buttons.tsx	OAuth sign-in buttons
components/user-menu.tsx	User dropdown menu
app/providers.tsx	SessionProvider wrapper
types/next-auth.d.ts	Extended types
lib/auth-helpers.ts	Auth utility functions

Security Considerations

• Use AUTH_SECRET from environment
• Set httpOnly cookies
• Implement CSRF protection
• Hash passwords with bcrypt (min 12 rounds)
• Validate all inputs
• Rate limit authentication endpoints