# Auth JS Boiler 🔐

A modern, full-stack authentication boilerplate built with Next.js, Auth.js (formerly Next-Auth), Prisma, and TypeScript. Stop rebuilding authentication systems from scratch for every project!

<p align="center">
  <img alt="Version" src="https://img.shields.io/badge/version-0.1.0-blue.svg"/>
  <img alt="License" src="https://img.shields.io/badge/license-MIT-green.svg"/>
</p>

<h2 align="center">
  <a href="https://github.com/Mohamed-gp/auth-js-boiler">
    <b>Complete Authentication Solution</b>
  </a>
</h2>

## 🎥 Demo

https://github.com/user-attachments/assets/f1bf4f2e-c66f-4be5-9cf7-5f9c17c7c23c

## ✨ Features

- 🔒 **Complete Authentication Flow**
  - Email & Password Sign Up/Sign In
  - Email Verification
  - Forgot Password & Password Reset
  - Account Settings & Profile Management
- 🌐 **OAuth Integration**
  - Google Authentication
  - GitHub Authentication
  - Easily extendable to other providers
- 🛡️ **Enhanced Security**
  - Two-Factor Authentication (2FA)
  - Role-Based Access Control (User, Admin, Moderator)
  - CSRF Protection
  - Rate Limiting
- 💾 **Database & Storage**
  - PostgreSQL integration with Prisma ORM
  - Structured data models for User, Account, Session
- 🎨 **Polished UI Components**
  - Responsive design with Tailwind CSS
  - Shadcn UI component library integration
  - Form validation with Zod & React Hook Form
- 📧 **Email Services**
  - Verification emails
  - Password reset emails
  - Customizable email templates
- ⚙️ **User Settings Page**
  - Profile information management
  - Password changing functionality
  - Two-factor authentication toggle
  - Special handling for OAuth users
- 🚀 **Production-Ready**
  - Optimized for performance
  - Docker support for easy deployment
  - Comprehensive TypeScript types

## 🛠️ Tech Stack

- **Frontend**: Next.js 15, React 19, TypeScript
- **Styling**: Tailwind CSS, Shadcn UI (Radix UI)
- **Authentication**: Auth.js v5 (Next-Auth)
- **Database**: PostgreSQL with Prisma ORM
- **Form Handling**: React Hook Form with Zod validation
- **Utility Libraries**:
  - bcryptjs (password hashing)
  - nodemailer (email sending)
  - lucide-react (icons)

## 🚀 Getting Started

### Prerequisites

- Node.js 18+ and npm/yarn/pnpm
- PostgreSQL database

### Installation

1. Clone the repository

   ```bash
   git clone https://github.com/Mohamed-gp/auth-js-boiler.git
   cd auth-js-boiler
   ```

2. Install dependencies

   ```bash
   npm install
   # or
   yarn install
   # or
   pnpm install
   ```

3. Configure environment variables

   ```bash
   cp .env.example .env.local
   # Edit .env.local with your configuration
   ```

4. Set up the database

   ```bash
   npm run prisma:generate
   npm run prisma:push
   ```

5. Start the development server
   ```bash
   npm run dev
   ```

## 📋 Available Scripts

- `npm run dev` - Start the development server
- `npm run build` - Build the application for production
- `npm run start` - Start the production server
- `npm run lint` - Run ESLint to check for code issues

### Prisma Commands

- `npm run prisma:studio` - Open Prisma Studio to manage your database
- `npm run prisma:generate` - Generate Prisma client
- `npm run prisma:migrate` - Create and apply migrations
- `npm run prisma:push` - Push schema changes without migrations
- `npm run prisma:pull` - Pull the current database schema
- `npm run prisma:seed` - Seed the database with initial data
- `npm run prisma:format` - Format the schema file
- `npm run prisma:reset` - Reset the database (use with caution)

## 🧩 Project Structure

```
auth-js-boiler/
├── prisma/                  # Database schema and migrations
├── public/                  # Static assets
├── src/
│   ├── actions/             # Server actions for forms and API
│   ├── app/                 # Next.js app router
│   │   ├── api/             # API routes
│   │   ├── auth/            # Authentication pages
│   │   └── admin/           # Admin dashboard
│   ├── components/          # React components
│   │   ├── ui/              # UI components (shadcn)
│   │   └── form/            # Form components
│   ├── lib/                 # Utility functions
│   ├── schemas/             # Zod validation schemas
│   └── types/               # TypeScript type definitions
├── tailwind.config.ts       # Tailwind configuration
└── next.config.mjs          # Next.js configuration

## 🔒 Authentication Flow

The authentication system includes:

1. **Registration** - Create account with email/password
2. **Email Verification** - Verify email with token
3. **Login** - Sign in with credentials or OAuth providers
4. **2FA** - Optional two-factor authentication
5. **Password Reset** - Forgot password flow
6. **Session Management** - JWT-based sessions

## 🛣️ Roadmap

- [ ] Add more OAuth providers
- [ ] Implement WebAuthn support
- [ ] Add Magic Link authentication
- [ ] Create comprehensive documentation site
- [ ] Add more role-based templates

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgements

- [Next.js](https://nextjs.org/)
- [Auth.js](https://authjs.dev/)
- [Prisma](https://prisma.io/)
- [Tailwind CSS](https://tailwindcss.com/)
- [Shadcn UI](https://ui.shadcn.com/)

---

Built with ❤️ to save developers time and headaches.
```