Installation

Prerequisites

Before installing the load balancer, ensure you have the Bun runtime installed.

Install Bun

Bun is a fast JavaScript runtime and package manager that powers this load balancer.

curl -fsSL https://bun.sh/install | bash

Verify the installation:

bun --version

You should see version 1.0.0 or higher.

Why Bun? This project uses Bun for its exceptional performance, built-in TypeScript support without compilation, and fast package installation. The load balancer can handle high request throughput thanks to Bun’s optimized HTTP primitives.

Installation steps

Clone the repository

Clone the project from GitHub:

git clone https://github.com/rishav76dev/LoadBalancer.git
cd LoadBalancer

Install dependencies

Install all required packages using Bun:

bun install

This installs:

express - HTTP server framework
express-http-proxy - Reverse proxy middleware
dotenv - Environment variable management
TypeScript types for development

Verify installation

Confirm everything is set up correctly by running:

bun run start

You should see:

INFO: Load balancer running on port 3000
INFO: Backend servers: http://localhost:3001, http://localhost:3002, http://localhost:3003
INFO: Health checker started (checking every 5s)

The load balancer will start even if backend servers aren’t running yet. You’ll see health check failures until you start the backends.

Project structure

Here’s the complete directory layout:

loadbalancer/
├── src/
│   ├── index.ts                  # Entry point - wires all components
│   ├── balancer/
│   │   ├── loadBalancer.ts       # Core balancer orchestration
│   │   ├── pool.ts               # Backend pool management
│   │   └── roundRobin.ts         # Round-robin strategy
│   ├── healthchecker/
│   │   └── healthChecker.ts      # Periodic health monitoring
│   ├── proxy/
│   │   └── proxyHandler.ts       # Express middleware for proxying
│   ├── types/
│   │   └── types.ts              # TypeScript interfaces
│   └── utils/
│       └── logger.ts             # Structured logging utilities
├── package.json                  # Project metadata and scripts
├── tsconfig.json                 # TypeScript configuration
├── bun.lock                      # Dependency lock file
└── README.md                     # Project documentation

Key directories explained

src/balancer/ — Contains the core load balancing logic. The LoadBalancer class orchestrates the BackendPool and routing RoundRobin strategy to select backends for incoming requests. src/healthchecker/ — Implements periodic health checks using fetch() with timeout controllers. Runs checks in parallel and updates the backend pool’s health status. src/proxy/ — Contains the Express middleware that forwards requests to selected backends using express-http-proxy. Handles errors and marks backends as unhealthy on failures. src/types/ — Defines TypeScript interfaces used across the application. Currently contains the Backend interface with url and health properties. src/utils/ — Utility modules including the structured logger that provides color-coded, categorized logging for requests, responses, health checks, and errors.

Configuration

The load balancer is configured directly in src/index.ts. You can customize:

Backend servers

Edit the backendUrls array to add or remove backend servers:

src/index.ts

const backendUrls = [
    "http://localhost:3001",
    "http://localhost:3002",
    "http://localhost:3003",
    "http://localhost:3004", // Add more backends
];

Health check interval

Change the health check frequency by modifying the second parameter (in milliseconds):

src/index.ts

// Check every 10 seconds instead of 5
const healthChecker = new HealthChecker(backendPool, 10000);

Load balancer port

Change the port the load balancer listens on:

src/index.ts

const PORT = 8080; // Use port 8080 instead of 3000

For production deployments, consider moving these configurations to environment variables using the included dotenv package.

Available scripts

The package.json defines these npm scripts:

Script	Command	Description
`start`	`bun run src/index.ts`	Start the load balancer in production mode
`dev`	`bun --watch src/index.ts`	Start with auto-reload on file changes
`build`	`tsc -b`	Compile TypeScript to JavaScript

Running in development mode

For development with automatic reload:

bun run dev

This uses Bun’s --watch flag to restart the server whenever source files change.

Building for production

While Bun can run TypeScript directly, you can compile to JavaScript:

bun run build

Compiled files will be output according to your tsconfig.json settings.

Environment setup

The project includes dotenv for environment variable management. Create a .env file in the project root for environment-specific configuration:

.env

# Load balancer configuration
PORT=3000
HEALTH_CHECK_INTERVAL=5000

# Backend servers (comma-separated)
BACKEND_URLS=http://localhost:3001,http://localhost:3002,http://localhost:3003

# Logging
LOG_LEVEL=info

The current implementation uses hardcoded values in src/index.ts. To use environment variables, you’ll need to load them with dotenv and update the configuration accordingly.

TypeScript configuration

The project uses strict TypeScript settings defined in tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Strict mode ensures type safety and catches potential errors at compile time.

Troubleshooting

Bun command not found

If you get “command not found” after installing Bun, restart your terminal or add Bun to your PATH:

export PATH="$HOME/.bun/bin:$PATH"

Add this line to your ~/.bashrc or ~/.zshrc to make it permanent.

Port already in use

If port 3000 is already in use, either:

Stop the process using that port
Change the PORT constant in src/index.ts to a different value

Health checks failing

If you see continuous health check failures, ensure:

Backend servers are running on the configured ports
The backend URLs in backendUrls are correct
No firewall is blocking connections to localhost

Next steps

Quickstart guide

Get up and running with test backends in 5 minutes

Architecture overview

Learn how the components work together

API reference

Explore the core classes and methods

Extending strategies

Add custom load balancing algorithms

Get Started

Architecture

Core Concepts

Operations

Prerequisites

Install Bun

Installation steps

Project structure

Key directories explained

Configuration

Backend servers

Health check interval

Load balancer port

Available scripts

Running in development mode

Building for production

Environment setup

TypeScript configuration

Troubleshooting

Bun command not found

Port already in use

Health checks failing

Next steps

Quickstart guide

Architecture overview

API reference

Extending strategies

Build docs developers (and LLMs) love

Get Started

Architecture

Core Concepts

Operations

​Prerequisites

​Install Bun

​Installation steps

​Project structure

​Key directories explained

​Configuration

​Backend servers

​Health check interval

​Load balancer port

​Available scripts

​Running in development mode

​Building for production

​Environment setup

​TypeScript configuration

​Troubleshooting

​Bun command not found

​Port already in use

​Health checks failing

​Next steps

Quickstart guide

Architecture overview

API reference

Extending strategies

Build docs developers (and LLMs) love

Prerequisites

Install Bun

Installation steps

Project structure

Key directories explained

Configuration

Backend servers

Health check interval

Load balancer port

Available scripts

Running in development mode

Building for production

Environment setup

TypeScript configuration

Troubleshooting

Bun command not found

Port already in use

Health checks failing

Next steps