🚀 A production-ready, batteries-included TypeScript + Express.js boilerplate with modern tooling, structured logging, request validation, rate limiting, and more.

TS-BoilerplateX gives developers a robust starting point for building powerful REST APIs and web applications. It combines TypeScript's static typing with Express.js 5's flexibility, pre-configured with industry best practices for security, observability, and developer experience.

• Node.js >= 18.0.0
• npm >= 9.0.0

npx ts-boilerplatex

# Clone the repository
git clone https://github.com/eldhopaulose/TS-BoilerplateX.git
cd TS-BoilerplateX

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Start development server
npm run dev

The server will start at http://localhost:3000 with hot-reload enabled.

TS-BoilerplateX/
├── src/
│   ├── bin/
│   │   └── server.ts              # HTTP server creation & lifecycle
│   ├── controller/
│   │   ├── indexController.ts     # Root route handler (API index)
│   │   └── userController.ts      # User CRUD handlers with logging
│   ├── middleware/
│   │   ├── index.ts               # Barrel export for all middleware
│   │   ├── rateLimiter.ts         # Global & strict rate limiters
│   │   ├── requestId.ts           # UUID-based request ID tracking
│   │   └── validate.ts            # Zod schema validation middleware
│   ├── models/
│   │   └── user.model.ts          # User data model (in-memory store)
│   ├── routes/
│   │   ├── health.ts              # Health check endpoint
│   │   ├── index.ts               # Root routes
│   │   └── user.routes.ts         # User CRUD routes with validation
│   ├── schemas/
│   │   └── user.schema.ts         # Zod validation schemas for User API
│   ├── types/
│   │   └── express.d.ts           # Express type augmentations
│   ├── utils/
│   │   └── logger.ts              # Pino logger configuration
│   └── main.ts                    # Application entry point
├── .env.example                   # Environment variable template
├── eslint.config.mjs              # ESLint 10 flat config
├── nodemon.json                   # Development server config
├── package.json
├── tsconfig.json                  # TypeScript compiler config
└── README.md

The boilerplate ships with a fully working User CRUD API that demonstrates all features. Start the server and try:

1. List all users (with pagination & filtering):

curl http://localhost:3000/api/users?page=1&limit=10

# Filter by role
curl http://localhost:3000/api/users?role=admin

# Filter by active status
curl http://localhost:3000/api/users?isActive=true

Response:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Eldho Paulose",
      "email": "eldho@example.com",
      "age": 28,
      "role": "admin",
      "isActive": true,
      "createdAt": "2026-03-27T12:00:00.000Z",
      "updatedAt": "2026-03-27T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "limit": 10,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

2. Create a new user:

curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "age": 30,
    "role": "moderator"
  }'

Response (201):

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "age": 30,
    "role": "moderator",
    "isActive": true,
    "createdAt": "2026-03-27T12:01:00.000Z",
    "updatedAt": "2026-03-27T12:01:00.000Z"
  }
}

3. Validation error example (missing required fields):

curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "A"}'

Response (422):

{
  "error": "Validation Error",
  "details": [
    { "field": "body.name", "message": "Name must be at least 2 characters" },
    { "field": "body.email", "message": "Required" },
    { "field": "body.age", "message": "Required" }
  ]
}

4. Update a user:

curl -X PUT http://localhost:3000/api/users/<user-id> \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Smith", "age": 31}'

5. Delete a user:

curl -X DELETE http://localhost:3000/api/users/<user-id>

6. Get user statistics:

curl http://localhost:3000/api/users/stats

Response:

{
  "success": true,
  "data": {
    "total": 3,
    "active": 2,
    "inactive": 1,
    "byRole": { "admin": 1, "user": 1, "moderator": 1 },
    "averageAge": 28
  }
}

7. Health check:

curl http://localhost:3000/api/health

Pino provides ultra-fast, structured JSON logging in production and colorful, readable output in development.

import logger from "./utils/logger";

logger.info("Server started");
logger.error({ err: error }, "Database connection failed");
logger.debug({ userId: 123 }, "User fetched");

Development output:

[12:34:56] INFO: Incoming request
    method: "GET"
    url: "/api/health"
    requestId: "550e8400-e29b-41d4-a716-446655440000"

Production output (JSON):

{"level":"info","time":"2026-03-27T12:34:56.789Z","method":"GET","url":"/api/health","requestId":"550e8400-e29b-41d4-a716-446655440000","msg":"Incoming request"}

Type-safe request validation using Zod schemas:

import { z } from "zod";
import { validate } from "../middleware/validate";

const createUserSchema = z.object({
  body: z.object({
    name: z.string().min(1, "Name is required"),
    email: z.string().email("Invalid email address"),
    age: z.number().int().min(18, "Must be at least 18"),
  }),
});

router.post("/users", validate(createUserSchema), userController.create);

Validation error response (422):

{
  "error": "Validation Error",
  "details": [
    { "field": "body.email", "message": "Invalid email address" },
    { "field": "body.age", "message": "Must be at least 18" }
  ]
}

Two-tier rate limiting out of the box:

import { globalRateLimiter, strictRateLimiter } from "../middleware";

// Global: applied to all routes (100 req/15min by default)
app.use(globalRateLimiter);

// Strict: for sensitive endpoints (10 req/15min by default)
router.post("/auth/login", strictRateLimiter, authController.login);

Every request gets a unique UUID via the X-Request-Id header. Pass an existing ID from upstream services, or one will be auto-generated:

# Auto-generated
curl http://localhost:3000/
# Response header: X-Request-Id: 550e8400-e29b-41d4-a716-446655440000

# Pass your own
curl -H "X-Request-Id: my-trace-id" http://localhost:3000/
# Response header: X-Request-Id: my-trace-id

Built-in health check endpoint for load balancers and container orchestration:

curl http://localhost:3000/api/health

{
  "status": "ok",
  "uptime": 123.456,
  "timestamp": "2026-03-27T12:34:56.789Z",
  "memoryUsage": {
    "rss": "45.23 MB",
    "heapUsed": "22.11 MB",
    "heapTotal": "35.50 MB"
  },
  "environment": "development"
}

The server handles SIGTERM and SIGINT signals gracefully, allowing in-flight requests to complete before shutting down (with a 10-second timeout):

// Automatically handled — no configuration needed
// Logs: "Received SIGTERM. Shutting down gracefully..."
// Logs: "HTTP server closed."

The following middleware is applied in order:

1. Helmet — Sets secure HTTP headers (XSS protection, CSP, etc.)
2. CORS — Enables cross-origin requests
3. Rate Limiter — Prevents abuse with configurable limits
4. Request ID — Assigns unique trace IDs to each request
5. Pino Logger — Logs every incoming request with method, URL, and trace ID
6. Body Parser — Parses JSON and URL-encoded bodies (up to 10MB)
7. Compression — Gzip compresses response bodies
8. Cookie Parser — Parses cookies from request headers

Contributions are welcome! Feel free to open an issue or submit a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Licensed under the Apache-2.0. See the LICENSE file for details.

Made with ❤️ by Eldho Paulose