Full-Stack Authentication Template

A production-ready full-stack authentication template with React, TypeScript, Express, and MongoDB.

🎨 This is a template repository - Use it as a starting point for your projects!

✨ Features

• 🔐 Complete Authentication System

  • User registration and login
  • JWT-based authentication
  • Password reset via email
  • Secure password hashing with bcrypt

• 🎨 Modern Frontend

  • React 18 with TypeScript
  • Tailwind CSS for styling
  • React Router for navigation
  • React Hook Form + Zod for validation
  • TanStack Query for server state management

• ⚡ Robust Backend

  • Express.js REST API
  • MongoDB with Mongoose
  • Input validation with Zod
  • Comprehensive error handling
  • Winston logger

• 🧪 Testing Ready

  • Jest configuration
  • Unit test examples
  • MongoDB Memory Server for testing

🚀 Quick Start

Prerequisites

• Node.js (v18 or higher)
• MongoDB (local or Atlas)
• npm or yarn

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd fullstack-auth-template

2. Install dependencies

   # Install backend dependencies
   cd backend
   npm install
   
   # Install frontend dependencies
   cd ../frontend
   npm install

3. Configure environment variables

   Create .env files by copying the example files:

   # macOS/Linux
   cp backend/.env.example backend/.env
   cp frontend/.env.example frontend/.env
   
   # Windows (Command Prompt)
   copy backend\.env.example backend\.env
   copy frontend\.env.example frontend\.env
   
   # Windows (PowerShell)
   Copy-Item backend\.env.example backend\.env
   Copy-Item frontend\.env.example frontend\.env

   Backend (backend/.env):

   # Application Settings
   APP_NAME=Your App Name
   
   # Server Configuration
   PORT=5000
   NODE_ENV=development
   
   # Database
   DATABASE_URL=mongodb://localhost:27017/your-project-name
   
   # JWT Configuration
   JWT_SECRET=your-super-secret-jwt-key-change-this-in-production-min-32-chars
   JWT_EXPIRES_IN=15m
   JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-this-in-production-32
   JWT_REFRESH_EXPIRES_IN=7d
   
   # Frontend URL
   FRONTEND_URL=http://localhost:5173
   
   # Email Configuration (for password reset emails)
   EMAIL_HOST=smtp.gmail.com
   EMAIL_PORT=587
   EMAIL_USER=your-email@gmail.com
   EMAIL_PASSWORD=your-app-password
   EMAIL_FROM=noreply@yourapp.com

   Frontend (frontend/.env):

   # Application Settings
   VITE_APP_NAME=Your App Name
   
   # API Configuration
   VITE_API_URL=http://localhost:5000/api

4. Start MongoDB

   Option A: Local MongoDB

   # Windows
   mongod --dbpath C:\data\db
   
   # macOS/Linux
   mongod --dbpath /path/to/your/db
   
   # Or if MongoDB is installed as a service
   # Windows: Already running as service
   # macOS: brew services start mongodb-community
   # Linux: sudo systemctl start mongod

   Option B: MongoDB Atlas

   • Create a free cluster at MongoDB Atlas
   • Get your connection string
   • Update DATABASE_URL in backend/.env with your Atlas connection string

5. Start the development servers

   Open two new terminal windows:

   Terminal 1 - Backend

   cd backend
   npm run dev

   Terminal 2 - Frontend

   cd frontend
   npm run dev

6. Open your browser

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:5000/api

🎨 Customization

To customize this template for your project:

1. Update Application Name

   • Set APP_NAME in backend/.env
   • Set VITE_APP_NAME in frontend/.env

2. Update Database Name

   • Change your-project-name in DATABASE_URL to your project name

3. Update package.json

   • Change name, description, and other fields in both backend/package.json and frontend/package.json

4. Customize Branding

   • Replace logo in frontend/public/
   • Update colors in Tailwind config if needed
   • Modify page titles and descriptions

📁 Project Structure

fullstack-auth-template/
├── backend/
│   ├── src/
│   │   ├── config/          # Configuration files
│   │   ├── controllers/     # Route controllers
│   │   ├── middleware/      # Express middleware
│   │   ├── models/          # Mongoose models
│   │   ├── routes/          # API routes
│   │   ├── services/        # Business logic
│   │   ├── utils/           # Utility functions
│   │   ├── validators/      # Input validation
│   │   └── server.ts        # Entry point
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── api/             # API client
│   │   ├── components/      # React components
│   │   ├── hooks/           # Custom hooks
│   │   ├── pages/           # Page components
│   │   ├── store/           # State management
│   │   ├── utils/           # Utility functions
│   │   └── validators/      # Form validation
│   └── package.json
└── docs/                    # Documentation

🛠️ Tech Stack

Frontend

• React 18 - UI library
• TypeScript - Type safety
• Vite - Build tool
• Tailwind CSS - Styling
• React Router - Routing
• React Hook Form - Form handling
• Zod - Schema validation
• TanStack Query - Server state
• Zustand - Client state
• Axios - HTTP client

Backend

• Node.js - Runtime
• Express - Web framework
• TypeScript - Type safety
• MongoDB - Database
• Mongoose - ODM
• JWT - Authentication
• bcrypt - Password hashing
• Zod - Validation
• Winston - Logging
• Nodemailer - Email sending

📚 Documentation

• API Specification
• Architecture Overview
• Database Schema

🧪 Testing

# Backend tests
cd backend
npm test
npm run test:coverage

🚀 Production Build

# Build backend
cd backend
npm run build

# Build frontend
cd frontend
npm run build

📝 License

MIT

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

---

Made with ❤️ using React, Express, and MongoDB