Express BuildKit

📚 Documentation

• Complete API Documentation - Detailed API reference with examples
• Contributing Guide - Guidelines for contributing to the project
• Changelog - Version history and updates
• License - MIT License

Overview

A comprehensive TypeScript utility library for Express.js applications. Express BuildKit provides standardized API response helpers, middleware management, validation utilities, and more to help you build robust and consistent Express applications.

Features

• 🚀 Standardized API Responses - Consistent response format across your entire API
• 🛡️ Built-in Middleware - Pre-configured CORS, rate limiting, and body parsing
• ✅ Validation Helpers - Seamless integration with Zod for request validation
• 🔧 TypeScript First - Full TypeScript support with comprehensive type definitions
• 📦 Zero Config - Works out of the box with sensible defaults
• ⚡ Lightweight - Minimal dependencies, maximum performance
• 🎯 Express 4 & 5 - Compatible with both Express.js versions

Installation

npm install express-buildkit

or with yarn:

yarn add express-buildkit

Quick Start

import express from 'express';
import { 
  applyMiddlewaresOnApp, 
  sendApiSuccessResponse,
  configureExpressBuildKit 
} from 'express-buildkit';

// Configure global settings (optional)
configureExpressBuildKit({
  rateLimiterOptions: {
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 100 // limit each IP to 100 requests per windowMs
  }
});

const app = express();

// Apply built-in middlewares
applyMiddlewaresOnApp(app, {
  applyCors: true,
  expressJson: true,
  expressUrlEncoded: true,
  applyRateLimiter: true
});

// Your routes
app.get('/api/users', (req, res) => {
  const users = [{ id: 1, name: 'John Doe' }];
  
  sendApiSuccessResponse(res, {
    message: 'Users fetched successfully',
    dataList: users
  });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Core Features

API Response Helpers

Express BuildKit provides a consistent API response format:

{
  success: boolean;
  message: string;
  result: {
    data?: any;
    dataList?: any[];
    authToken?: string;
  };
  errors: any[];
  code: number;
  status: number;
}

Available Response Functions

// Success response
sendApiSuccessResponse(res, {
  message: 'Operation successful',
  data: { id: 1, name: 'John' }
});

// Failed response
sendApiFailedResponse(res, {
  message: 'Operation failed',
  errors: ['Invalid input']
});

// Specific error responses
sendBadRequestResponse(res, { message: 'Invalid request data' });
sendUnAuthenticatedErrorResponse(res, { message: 'Please login first' });
sendUnAuthorizedErrorResponse(res, { message: 'Access denied' });
sendNotFoundErrorResponse(res, { message: 'Resource not found' });
sendTooManyRequestsErrorResponse(res, { message: 'Rate limit exceeded' });
sendItemExistsErrorResponse(res, { message: 'Item already exists' });

Middleware Management

Apply common middlewares with a single function call:

applyMiddlewaresOnApp(app, {
  applyCors: true,        // Enable CORS
  expressJson: true,      // Parse JSON bodies
  expressUrlEncoded: true,// Parse URL-encoded bodies
  applyRateLimiter: true  // Apply rate limiting
});

// Add invalid route handler
invalidRequestHandler(app);

Request Validation

Integrate Zod schemas for request validation:

import { z } from 'zod';
import { validateRequestInputData } from 'express-buildkit';

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

app.post('/api/users', async (req, res) => {
  const validatedData = await validateRequestInputData(req, res, createUserSchema);
  
  // If validation fails, error response is automatically sent
  if (!validatedData) return;
  
  // Use validated data with full type safety
  console.log(validatedData.name); // TypeScript knows this is a string
});

Built-in Validation Schemas

Express BuildKit includes pre-built validation schemas for common use cases:

import { 
  loginRequestValidationSchema,
  registerRequestValidationSchema 
} from 'express-buildkit';

// Login endpoint
app.post('/api/login', async (req, res) => {
  const credentials = await validateRequestInputData(
    req, 
    res, 
    loginRequestValidationSchema
  );
  if (!credentials) return;
  
  // credentials.email and credentials.password are validated
});

// Register endpoint
app.post('/api/register', async (req, res) => {
  const userData = await validateRequestInputData(
    req, 
    res, 
    registerRequestValidationSchema
  );
  if (!userData) return;
  
  // userData includes name, email, password, and passwordConfirmation
});

Configuration

Configure global settings for Express BuildKit:

import { configureExpressBuildKit } from 'express-buildkit';

configureExpressBuildKit({
  rateLimiterOptions: {
    windowMs: 15 * 60 * 1000,  // Time window in milliseconds
    max: 100,                   // Max requests per window
    message: 'Too many requests', // Error message
    standardHeaders: true,      // Return rate limit info in headers
    legacyHeaders: false,       // Disable X-RateLimit headers
  }
});

API Reference

For detailed API documentation, see DOCUMENTATION.md.

TypeScript Support

Express BuildKit is written in TypeScript and provides comprehensive type definitions:

import type { 
  IApiResponse,
  IApplyMiddlewareOptions,
  IConfigureExpressBuildKitOptions 
} from 'express-buildkit';

Best Practices

1. Always validate input data - Use the validation helpers to ensure data integrity
2. Use consistent responses - Stick to the provided response helpers for API consistency
3. Configure rate limiting - Protect your API from abuse with appropriate rate limits
4. Handle errors gracefully - Use the specific error response functions for clear communication

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

License

MIT © Ahsan Mahmood

Author

Ahsan Mahmood

• Website: aoneahsan.com
• GitHub: @aoneahsan
• Email: [email protected]

Made with ❤️ by Ahsan Mahmood