Express TypeScript Supabase Boilerplate

A production-ready, enterprise-grade Node.js + Express.js backend boilerplate with TypeScript, Supabase, comprehensive security, email verification, real-time monitoring, and extensive testing.

🚀 Features

Core Technologies

• TypeScript - Full TypeScript support with strict type checking and advanced error handling
• Express.js 5.x - Latest Express framework with enhanced performance
• Supabase - Open source Firebase alternative with PostgreSQL and real-time capabilities
• Node.js - Latest LTS version with optimal performance configurations

Security & Authentication

• JWT Authentication - Secure JWT-based authentication with refresh token rotation
• Email Verification - Complete email verification system with secure token generation
• Advanced Security Middleware - Helmet, CORS, Rate limiting, and DDoS protection
• Input Sanitization - Comprehensive XSS, SQL injection, and NoSQL injection protection
• Express v5 Compatible - Updated sanitization for Express v5 read-only properties
• Row Level Security (RLS) - Production-ready Supabase RLS policies
• Path Traversal Protection - Prevents directory traversal attacks
• Content Security Policy - Configurable CSP headers for enhanced security
• Password Security - Bcrypt hashing with configurable salt rounds

Validation & Error Handling

• Comprehensive Validation - Advanced request validation with express-validator
• Structured Error Codes - Standardized error codes with detailed error responses
• Custom Validation Schemas - Organized validation schemas for different entities
• File Upload Validation - Secure file upload with type and size validation
• Rate Limiting - Configurable rate limiting with different strategies

Development & Testing

• Extensive Testing - Unit tests, integration tests, and security tests
• Code Quality - ESLint v9, Prettier, and TypeScript strict mode
• Structured Logging - Winston logger with different log levels and formats
• Environment Configuration - Comprehensive environment-based configuration
• API Documentation - Built-in API documentation and health checks

Performance & Monitoring

• Real-time Health Monitoring - Live server uptime, database status, and system metrics
• Supabase Connection Monitoring - Real-time database response time and status
• Memory Usage Tracking - Live server memory monitoring with formatted display
• Response Time Classification - Performance status indicators (excellent/good/fair/poor)
• Compression - Response compression for better performance
• Request Logging - Detailed request/response logging with correlation IDs
• Graceful Shutdown - Proper application lifecycle management

📁 Project Structure

src/
├── config/           # Configuration files
│   ├── database.ts   # Supabase configuration
│   ├── logger.ts     # Winston logger setup
│   ├── production.ts # Production configuration manager
│   └── security.ts   # Security middleware configuration
├── database/         # Database schema and migrations
│   └── schema.sql    # Database schema
├── constants/        # Application constants
│   └── errorCodes.ts # Standardized error codes
├── controllers/      # Route controllers
│   ├── authController.ts
│   ├── emailController.ts
│   ├── healthController.ts
│   └── userController.ts
├── middlewares/      # Custom middleware
│   ├── auth.ts       # Authentication middleware
│   ├── errorHandler.ts # Error handling middleware
│   └── performance.ts # Performance monitoring middleware
├── routes/           # Route definitions
│   ├── authRoutes.ts
│   ├── emailRoutes.ts
│   ├── healthRoutes.ts
│   ├── userRoutes.ts
│   └── index.ts
├── services/         # Business logic services
│   ├── authService.ts
│   ├── emailService.ts
│   └── userService.ts
├── utils/            # Utility functions
│   └── formatters.ts # Data formatting utilities
├── types/            # TypeScript type definitions
│   ├── database.ts   # Database types
│   └── index.ts      # Common types
├── validation/       # Validation schemas and middleware
│   ├── schemas/      # Validation schemas
│   │   ├── authValidation.ts
│   │   ├── userValidation.ts
│   │   └── commonValidation.ts
│   ├── middleware/   # Validation middleware
│   │   ├── validationHandler.ts
│   │   └── sanitization.ts
│   └── index.ts
├── tests/            # Test files
│   ├── unit/         # Unit tests
│   │   ├── authService.test.ts
│   │   └── validation.test.ts
│   └── integration/  # Integration tests
│       └── auth.test.ts
├── docs/             # Documentation
│   ├── API.md        # API documentation
│   ├── DEPLOYMENT.md # Deployment guide
│   ├── SECURITY.md   # Security guide
│   └── OPTIMIZATION.md # Performance guide
└── index.ts          # Application entry point

logs/                       # Application logs (auto-created)
database-setup.sql          # Unified database setup file
DATABASE_SETUP.md           # Database setup guide

Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm, yarn, or pnpm
• Supabase account and project

Installation

1. Clone the repository

   git clone <repository-url>
   cd express-typescript-supabase-boilerplate
   

2. Install dependencies

   npm install
   # or
   yarn install
   # or
   pnpm install
   

3. Set up Supabase Database

   • Create a new project at supabase.com
   • Go to Settings > API to get your project URL and service role key
   • Go to SQL Editor and run the unified setup from database-setup.sql
   • See DATABASE_SETUP.md for detailed instructions

4. Configure environment variables

   cp .env.example .env
   

   Update .env with your Supabase credentials:

   SUPABASE_URL=your_supabase_project_url
   SUPABASE_ANON_KEY=your_supabase_anon_key
   SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
   JWT_SECRET=your_super_secret_jwt_key_here
   JWT_REFRESH_SECRET=your_super_secret_refresh_jwt_key_here
   

5. Start development server

   npm run dev
   

The server will start on http://localhost:5000 with API documentation at http://localhost:5000/.

API Documentation

Authentication Endpoints

Method	Endpoint	Description	Auth Required
POST	/api/auth/register	Register new user	No
POST	/api/auth/login	User login	No
POST	/api/auth/refresh	Refresh access token	No
POST	/api/auth/logout	User logout	No
GET	/api/auth/profile	Get user profile	Yes
POST	/api/auth/change-password	Change password	Yes

Email Verification Endpoints

Method	Endpoint	Description	Auth Required
GET	/api/email/verify?token=<token>	Verify email address	No
POST	/api/email/resend-verification	Resend verification email	No

User Management Endpoints

Method	Endpoint	Description	Auth Required	Admin Only
GET	/api/users/stats	Get user statistics	No	No
GET	/api/users/me	Get current user	Yes	No
GET	/api/users	List all users	Yes	Yes
GET	/api/users/:id	Get user by ID	Yes	No
PUT	/api/users/:id	Update user	Yes	No*
PATCH	/api/users/:id/deactivate	Deactivate user	Yes	Yes
PATCH	/api/users/:id/activate	Activate user	Yes	Yes
DELETE	/api/users/:id	Delete user	Yes	Yes
PATCH	/api/users/:id/role	Update user role	Yes	Yes

*Users can only update their own profile unless they're admin

Health Check

Method	Endpoint	Description
GET	/api/health	Real-time server and database health status

Health Check Response includes:

• Server uptime (real-time, formatted)
• Database connection status and response time
• Memory usage and system information
• Supabase project information
• Performance metrics and status indicators

Authentication Flow

1. Register: POST /api/auth/register

   {
     "name": "John Doe",
     "email": "john@example.com",
     "password": "SecurePass123!"
   }
   

   Note: Registration automatically sends a verification email

2. Verify Email: GET /api/email/verify?token=<verification_token>

   • Check server logs for verification link during development
   • In production, integrate with email service (SendGrid, AWS SES, etc.)

3. Login: POST /api/auth/login

   {
     "email": "john@example.com",
     "password": "SecurePass123!"
   }
   

4. Use Access Token: Include in Authorization header

   Authorization: Bearer <access_token>
   

5. Refresh Token: POST /api/auth/refresh (refresh token sent as httpOnly cookie)

6. Resend Verification (if needed): POST /api/email/resend-verification

   {
     "email": "john@example.com"
   }
   

Security Features

Rate Limiting

• General API: 100 requests per 15 minutes per IP
• Auth endpoints: 5 requests per 15 minutes per IP
• Slow down: Progressive delay after 50 requests

Input Validation

• Email format validation
• Password strength requirements (8+ chars, uppercase, lowercase, number, special char)
• Request sanitization to prevent XSS

Security Headers

• Helmet.js for security headers
• CORS with configurable origins
• Content Security Policy

Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	5000
NODE_ENV	Environment mode	development
SUPABASE_URL	Supabase project URL	Required
SUPABASE_ANON_KEY	Supabase anonymous key	Required
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key	Required
JWT_SECRET	JWT signing secret	Required
JWT_EXPIRES_IN	JWT expiration time	24h
JWT_REFRESH_SECRET	Refresh token secret	Required
JWT_REFRESH_EXPIRES_IN	Refresh token expiration	7d
BCRYPT_SALT_ROUNDS	Bcrypt salt rounds	12
RATE_LIMIT_WINDOW_MS	Rate limit window	900000
RATE_LIMIT_MAX_REQUESTS	Max requests per window	100
ALLOWED_ORIGINS	CORS allowed origins	http://localhost:3000
FRONTEND_URL	Frontend URL for email links	http://localhost:3000
LOG_LEVEL	Logging level	info

Database Setup

Unified Database Setup

The project includes a comprehensive, unified database setup file that handles:

• All Tables: users, refresh_tokens, user_sessions, email_verification_tokens
• Indexes: Performance-optimized indexes for all tables
• RLS Policies: Production-ready Row Level Security policies
• Functions & Triggers: Automatic timestamp updates
• Default Data: Admin user and sample data
• Verification Queries: Built-in setup verification

Quick Setup

1. Run database-setup.sql in your Supabase SQL Editor
2. The script is idempotent - safe to run multiple times
3. Includes verification queries to confirm successful setup
4. See DATABASE_SETUP.md for detailed instructions

Default Admin Account

• Email: admin@example.com
• Password: Admin123!@#
• ⚠️ Important: Change this password after first login!

Email Verification System

Development Mode

• Verification links are logged to the console
• Check server logs for verification URLs
• No external email service required for testing

Production Setup

To enable actual email sending, integrate with:

• SendGrid - Popular email service
• AWS SES - Amazon's email service
• Nodemailer - SMTP integration
• Other providers - Easy to ext