🚀 Express TypeScript Starter (v1.0.0)

📖 Table of Contents

Table of Contents

• Description
• Key Features
• Folder Structure
• Technologies Used
• Get Started
  • Prerequisites
  • Installation
  • Run Locally
• Scripts
• Environment Variables
• Health & Monitoring
• Contributing
• License

📝 Description

Express TypeScript Starter is a premium, production-ready boilerplate designed for building scalable and robust RESTful APIs. It combines the power of Express 5, TypeScript, and Prisma ORM with a strict focus on security, observability, and clean architecture.

Whether you're building a small service or a complex enterprise application, this starter provides the foundation you need to launch with confidence.

✨ Key Features

• 🛡️ Enhanced Security: Pre-configured with Helmet, HPP, CORS, and Rate Limiting.
• ⚡ Performance: Built on Express 5 with optimized asynchronous handling.
• 🦾 Strict Validation: Zod-based validation for request bodies, params, and even environment variables at startup.
• 🔄 Lifecycle Management: Graceful shutdown and health monitoring integrated via @godaddy/terminus.
• 📊 Observable Logging: Structured JSON logging using Pino and pino-http.
• 🏗️ Layered Architecture: Clean separation of concerns (Controllers, Services, Repositories).
• 🧪 Testing Ready: Pre-configured with Jest for unit and integration testing.

📂 Folder Structure

Project Layout

src/
├── __tests__/      # Automated unit and integration tests (Jest)
├── checks/         # System health monitoring (Database, Memory)
├── configs/        # Centralized configurations (Env, Logger, Prisma)
├── controllers/    # Request orchestration and HTTP logic
├── middlewares/    # Security, Auth, Logging and Error handlers
├── repositories/   # Data access layer (Prisma abstraction)
├── routers/        # API endpoint definitions
├── services/       # Core business logic implementation
├── types/          # TypeScript interfaces and shared types
├── utils/          # Global utility functions (JWT, Formatters)
├── validations/    # Zod schemas for request validation
└── index.ts        # Main entry point with Terminus integration

✨ Technologies Used

This project is built using the following premium stack:

• TypeScript: A typed superset of JavaScript for rock-solid code.
• Express 5: The legendary web framework, updated for the future.
• Prisma: Next-generation Node.js and TypeScript ORM.
• PostgreSQL: The world's most advanced open-source database.
• Zod: TypeScript-first schema declaration and validation.
• Pino: Super fast, low-overhead Node.js logger.
• Terminus: Graceful shutdown and health checks for Node.js.
• Jest: Delightful JavaScript Testing Framework.
• Helmet: Secure Express apps by setting various HTTP headers.

🧰 Get Started

Follow these steps to get your project running locally.

📋 Prerequisites

• Node.js (v18+)
• PostgreSQL (running instance)
• NPM or Yarn

⚙️ Installation

Step 1: Clone the Repo

git clone https://github.com/leapwithluvi/express-typescript-starter.git
cd express-typescript-starter

Step 2: Install Dependencies

npm install

Step 3: Setup Environment

cp .env.example .env
# Edit .env with your DATABASE_URL and JWT secrets

Step 4: Database Migration

npx prisma migrate dev

🚀 Run Locally

# Development mode with hot-reload
npm run dev

# Production build
npm run build
npm start

📜 Scripts

Script	Action
npm run dev	Starts local dev server with tsx watch
npm run build	Compiles TS to production JS (dist/)
npm start	Runs the production build
npm test	Executes tests using Jest
npm run lint	Runs ESLint for code quality
npm run prisma:generate	Generates the Prisma client

🔒 Environment Variables

The application uses strict validation—if these are missing or invalid, the app will refuse to start.

DATABASE_URL="postgresql://user:pass@localhost:5432/db"
PORT=3000
NODE_ENV="development" # or "production"

# JWT
JWT_SECRET="your-super-secret"
JWT_REFRESH_SECRET="your-refresh-secret"
JWT_ACCESS_EXPIRES_IN="15m"
JWT_REFRESH_EXPIRES_IN="7d"

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

🏥 Health & Monitoring

The API provides a built-in health check endpoint managed by Terminus:

• Endpoint: GET /health
• Checks:
  • Database: Verifies connectivity to PostgreSQL.
  • Memory: Monitors Heap and RSS usage against thresholds.

If any check fails, the endpoint returns a 503 Service Unavailable with detailed error info.

📋 License

This project is open-source and licensed under the MIT License. See LICENSE for more details.

---

Made by leapwithluvi