Node.js API Boilerplate

Enterprise-grade Node.js backend boilerplate with TypeScript, Express, Prisma, and comprehensive error handling.

🚀 Features

• ✅ Routes > Controller > Services architecture
• ✅ Comprehensive error handling with custom error classes
• ✅ Structured logging (development & production modes)
• ✅ Type-safe configuration with Zod validation
• ✅ Request validation middleware using Zod
• ✅ Standardized API responses
• ✅ API versioning (/api/v1)
• ✅ Graceful shutdown handling
• ✅ Database connection management (Prisma + SQLite)
• ✅ Request logging with timing
• ✅ 404 handling
• ✅ Async error handling wrapper
• ✅ TypeScript strict mode
• ✅ Kebab-case file naming

📁 Project Structure

src/
├── config/              # Configuration management
│   ├── config.ts        # Type-safe environment config
│   └── constants.ts     # Application constants
├── controllers/         # Request handlers
│   └── health.controller.ts
├── middleware/          # Express middleware
│   ├── async-handler.ts
│   ├── error-handler.ts
│   ├── not-found.ts
│   ├── request-logger.ts
│   └── validate-request.ts
├── routes/              # API routes
│   ├── health.route.ts
│   └── index.ts         # Route aggregator
├── services/            # Business logic
│   └── health.service.ts
├── types/               # TypeScript types
│   ├── api.types.ts
│   └── express.d.ts
├── utils/               # Utilities
│   ├── app-error.ts     # Custom errors
│   ├── logger.ts        # Structured logger
│   └── response-formatter.ts
└── index.ts             # Application entry point

🛠️ Tech Stack

• Runtime: Node.js
• Language: TypeScript
• Framework: Express 5
• Database: SQLite (via Prisma)
• ORM: Prisma
• Validation: Zod
• Dev Tools: tsx (TypeScript execution)

📦 Installation

# Install dependencies
npm install

# Generate Prisma client
npm run prisma:generate

# Run database migrations
npm run prisma:migrate

🚀 Usage

Development

npm run dev

Production

# Build
npm run build

# Start
npm start

Database Commands

# Generate Prisma client
npm run prisma:generate

# Run migrations
npm run prisma:migrate

# Open Prisma Studio
npm run prisma:studio

# Reset database
npm run prisma:reset

# Push schema changes
npm run db:push

# Seed database
npm run db:seed

🔌 API Endpoints

Health Check

• GET /api/v1/health - Comprehensive health status
• GET /api/v1/health/ping - Simple ping

Response Format

All API responses follow this structure:

{
  success: boolean,
  data?: any,
  error?: {
    message: string,
    code: string,
    details?: any
  },
  metadata?: {
    timestamp: string,
    requestId?: string,
    pagination?: {
      page: number,
      limit: number,
      total: number,
      totalPages: number
    }
  }
}

🏗️ Architecture

Routes > Controller > Services Pattern

Route - Defines endpoints and applies middleware

router.get("/", asyncHandler(controller.method));

Controller - Handles HTTP requests/responses

method = asyncHandler(async (req, res) => {
  const data = await this.service.method();
  ResponseFormatter.success(res, data);
});

Service - Contains business logic

async method() {
  // Business logic here
  return data;
}

🛡️ Error Handling

Custom Error Classes

• AppError - Base error class
• ValidationError - 400 Bad Request
• UnauthorizedError - 401 Unauthorized
• ForbiddenError - 403 Forbidden
• NotFoundError - 404 Not Found
• ConflictError - 409 Conflict
• InternalServerError - 500 Internal Server Error

Usage

throw new NotFoundError("User not found");
throw new ValidationError("Invalid email", "INVALID_EMAIL");

📝 Adding New Features

1. Create Service

// src/services/user.service.ts
export class UserService {
  async getUsers() {
    return await prisma.user.findMany();
  }
}

2. Create Controller

// src/controllers/user.controller.ts
export class UserController {
  private userService = new UserService();
  
  getUsers = asyncHandler(async (req, res) => {
    const users = await this.userService.getUsers();
    ResponseFormatter.success(res, users);
  });
}

3. Create Route

// src/routes/user.route.ts
const router = Router();
const userController = new UserController();

router.get("/", asyncHandler(userController.getUsers));

export default router;

4. Register Route

// src/routes/index.ts
import userRoute from "./user.route.js";
router.use(`${apiPrefix}/users`, userRoute);

🔍 Request Validation

Using Zod schemas:

import { z } from "zod";
import { validateRequest } from "../middleware/validate-request.js";

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
  age: z.number().min(18).optional(),
});

router.post(
  "/users",
  validateRequest({ body: createUserSchema }),
  asyncHandler(userController.create)
);

📊 Logging

import { logger } from "./utils/logger.js";

logger.info("User created", { userId: 123 });
logger.error("Database error", error);
logger.warn("Deprecated API used");
logger.debug("Debug information");

⚙️ Configuration

Environment variables are validated using Zod:

NODE_ENV=development
PORT=3000
DATABASE_URL=file:./dev.db
GEMINI_API_KEY=your_api_key
CORS_ORIGIN=*
LOG_LEVEL=info

🔒 Best Practices

• ✅ TypeScript strict mode enabled
• ✅ No any types (except where necessary)
• ✅ Async error handling
• ✅ Request validation
• ✅ Structured logging
• ✅ Graceful shutdown
• ✅ Database connection pooling
• ✅ Environment validation
• ✅ Consistent code style
• ✅ Kebab-case file naming

📄 License

ISC

👨‍💻 Author

Furkan Çakıcı