Next.js 15 + NextAuth v5 Starter Kit 🚀

---

✨ Features

📚 Table of Contents

• Quick Start
• Project Structure
• Authentication System
• Database Setup
• Running Tests
• Deployment
• Learn More

🚀 Quick Start

Prerequisites

• Node.js (18.17.0 or later)
• PostgreSQL database

Step 1: Clone & Install

# Clone the repository
git clone https://github.com/your-username/next15-nextauth-boilerplate.git

# Navigate to the project
cd next15-nextauth-boilerplate

# Install dependencies
npm install

Step 2: Environment Setup

Create a .env.local file in the root directory:

# Required environment variables
AUTH_SECRET=your-auth-secret
POSTGRES_URL=your-postgres-url

Generate a secure AUTH_SECRET:

openssl rand -base64 32

Step 3: Database Setup

# Generate database migrations
npm run db:generate

# Run migrations
npm run db:migrate

Step 4: Start Development Server

npm run dev

Visit http://localhost:3000 to see your application running.

📂 Project Structure

next15-nextauth-boilerplate/
│
├── 🗂️ app/                      # Next.js App Router
│   ├── (auth)/                 # Authentication routes
│   │   ├── auth.config.ts      # NextAuth configuration
│   │   ├── auth.ts             # Auth setup and providers
│   │   ├── actions.ts          # Server actions (login/register)
│   │   ├── login/              # Login page
│   │   └── register/           # Registration page
│   │
│   └── (dashboard)/            # Protected routes
│       ├── layout.tsx          # Dashboard layout
│       └── page.tsx            # Dashboard home
│
├── 🧩 components/               # Reusable React components
│   ├── auth-form.tsx           # Authentication form
│   ├── sign-out-form.tsx       # Sign out component
│   └── ui/                     # UI components
│
├── 📊 lib/                      # Utilities and libraries
│   └── db/                     # Database utilities
│       ├── schema.ts           # Drizzle schema definition
│       ├── queries.ts          # Database operations
│       └── migrations/         # Generated migrations
│
├── 🧪 tests/                    # Test files
│   ├── auth.setup.ts           # Authentication test setup
│   ├── auth.test.ts            # Auth flow tests
│   └── dashboard.test.ts       # Dashboard tests
│
├── 🔧 middleware.ts             # NextAuth middleware
├── ⚙️ drizzle.config.ts         # Drizzle ORM configuration
├── 🎭 playwright.config.ts      # Playwright test configuration
└── 📝 README.md                 # You are here!

🔐 Authentication System

This starter kit implements a complete authentication system using NextAuth v5 with email/password authentication.

📋 Authentication Flow

1️⃣ Registration Process

sequenceDiagram
    User->>+Frontend: Fill registration form
    Frontend->>+Server: Submit credentials
    Server->>Server: Validate input with Zod
    Server->>Server: Hash password with bcrypt
    Server->>+Database: Check if user exists
    Database-->>-Server: User exists/doesn't exist
    alt User exists
        Server-->>Frontend: Return error
    else User doesn't exist
        Server->>Database: Create new user
        Server->>Server: Create session
        Server-->>Frontend: Success & redirect
    end
    Frontend-->>-User: Show success/error

2️⃣ Login Process

• User submits credentials via login form
• Server validates the input
• Server checks credentials against database
• If valid, a session is created and user is redirected
• If invalid, an error message is displayed

3️⃣ Protected Routes

The middleware protects routes by:

• Checking for valid session
• Redirecting unauthenticated users to login
• Redirecting authenticated users away from auth pages

4️⃣ Sign Out

• User clicks "Sign out" button
• Session is destroyed
• User is redirected to login page

🛠️ Key Authentication Files

File	Purpose
auth.config.ts	Core NextAuth configuration
auth.ts	NextAuth setup with providers
actions.ts	Server actions for auth operations
middleware.ts	Route protection

💾 Database Setup

This starter uses Drizzle ORM with PostgreSQL for type-safe database access.

📊 Database Schema

// lib/db/schema.ts
export const user = pgTable('User', {
  id: uuid('id').primaryKey().notNull().defaultRandom(),
  email: varchar('email', { length: 64 }).notNull(),
  password: varchar('password', { length: 64 }),
});

🔍 Database Operations

The starter includes two main database operations:

1. Creating users - Securely hashes passwords before storage:

   export async function createUser(email: string, password: string)
   

2. Retrieving users - Finds users by email for authentication:

   export async function getUser(email: string): Promise<Array<User>>
   

🔄 Migrations

Database migrations are handled automatically:

# Generate migrations after schema changes
npm run db:generate

# Apply migrations to your database
npm run db:migrate

🧪 Running Tests

This starter includes comprehensive end-to-end tests with Playwright.

🧩 Test Structure

Tests are organized using the Page Object Model pattern for better maintainability:

// Example of AuthPage class
class AuthPage {
  constructor(private page: Page) {}
  
  async login(email: string, password: string) {
    await this.gotoLogin();
    await this.page.getByLabel('Email Address').fill(email);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Sign In' }).click();
  }
  
  // Other authentication methods...
}

🚦 Running the Test Suite

# Install Playwright browsers (first time only)
npx playwright install

# Run all tests
npm run test

# Run tests with visual UI
npm run test:ui

📋 What's Tested

🚀 Deployment

Vercel Deployment (Recommended)

1. Push your code to GitHub, GitLab, or Bitbucket
2. Import the project on Vercel
3. Configure your environment variables:
   • AUTH_SECRET
   • POSTGRES_URL
4. Deploy!

Alternative Hosting

For other hosting providers, ensure you:

1. Build the application with npm run build
2. Set up the required environment variables
3. Configure your database connection
4. Deploy the built application