Forem: Erick Engelhardt

Scaling Your Node.js App: An Introduction to Clustering

Erick Engelhardt — Fri, 13 Jun 2025 19:04:00 +0000

I’ve created a full example repo you can clone and experiment with:

👉 https://github.com/erickne/node-cluster

When you first spin up a Node.js server, everything runs in a single thread — meaning your app can only take advantage of one CPU core at a time. That’s great for simplicity, but... not so great when your users (and their requests) start piling up. 🧑‍💻➡️💥

Enter Node.js Clustering — a simple but powerful way to scale your app horizontally on a single machine by forking multiple processes that share the same server port.

How Does Node Work Under the Hood?

Before we dive deeper, it helps to understand a key part of Node’s architecture:

Node.js runs on Google’s V8 JavaScript engine — single-threaded for JS execution.
It uses a libuv-based event loop to handle I/O operations asynchronously.
However, CPU-bound operations and high concurrency can become bottlenecks — since your one event loop can only do so much.

When your app is bound by the CPU (e.g. doing data processing) or by the sheer number of concurrent users, this single-threaded model can start showing its limits.

Why Cluster?

🟢 Motivation: most modern CPUs are multi-core. Without clustering, you’re wasting a lot of potential.

By using Node’s built-in cluster module, you can:

Fork multiple Node.js processes (workers), one per CPU core.
Have these workers share the same server port (via the parent/master process).
Handle significantly more load by distributing incoming requests across these workers.

Benefits

✅ Utilize full CPU capacity
✅ Higher concurrency
✅ Increased resiliency (if a worker crashes, others can continue serving requests)
✅ Zero major code rewrites required to enable clustering

Risks & Tradeoffs

⚠️ Increased complexity (managing worker lifecycle, IPC communication)
⚠️ More memory usage (each worker is a full Node process)
⚠️ Not a silver bullet — clustering won’t fix poorly optimized code or non-scalable architecture.

When Should You Use Clustering?

Now that we know what clustering is and why it exists, let’s talk about the big question:

👉 Should you actually use it in your app?

Spoiler: it depends. 😅

Good Use Cases for Clustering

✅ CPU-Intensive Workloads
If your app does heavy data processing (crypto, image resizing, report generation), clustering helps distribute this across multiple cores.

✅ High Traffic APIs
For APIs with lots of concurrent requests, clustering helps prevent your single event loop from becoming a bottleneck.

✅ Web Servers
Apps built with frameworks like Express or Fastify often benefit a lot — since HTTP request handling can be easily parallelized.

✅ Better Fault Tolerance
If one worker crashes, the others stay alive — improving your app’s availability.

When NOT to Use Clustering

❌ Lightweight or Low Traffic Apps
If your app runs fine with a single thread and serves a small number of users, clustering might just add unnecessary complexity.

❌ Apps Already Behind a Load Balancer
If you’re running your app behind an external load balancer (Nginx, AWS ALB, Kubernetes, etc), clustering inside Node may not be needed — your infra is already distributing the load across multiple instances.

❌ Apps With Shared In-Memory State
If your app relies heavily on shared state (like an in-memory cache or user session object), clustering can cause consistency issues — each worker is a separate process with its own memory space.

📝 Tip: If you still want to cluster and need shared state, you’ll need to externalize it (Redis, database, etc).

Rule of Thumb

If your app is:

I/O-bound → maybe you don’t need clustering.
CPU-bound → clustering will likely help.
Memory-sensitive → clustering will increase memory usage.

Basic Example of Clustering in Node.js

The beauty of Node.js is that clustering is built right into the standard library. No extra dependencies required — you can use the cluster module and the os module to spin up workers across your CPU cores.

Let’s see it in action. 👇

Simple Cluster Example

import cluster from 'cluster';
import os from 'os';
import http from 'http';

const numCPUs = os.cpus().length;

if (cluster.isPrimary) {
  console.log(`Primary process ${process.pid} is running`);
  console.log(`Forking ${numCPUs} workers...`);

  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  // Optional: listen for worker exits
  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} exited. Spawning a new one.`);
    cluster.fork();
  });

} else {
  // Workers can share any TCP connection
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Handled by worker ${process.pid}\n`);
  }).listen(3000);

  console.log(`Worker ${process.pid} started`);
}

How It Works:

The primary process checks cluster.isPrimary === true and forks numCPUs workers.
Each worker starts an HTTP server on port 3000.
The OS automatically load-balances incoming connections across the workers.
If a worker dies, the primary process forks a new one (self-healing).

Running It

npm run start

Now when you hit http://localhost:3000, different requests will be handled by different worker processes.

👉 You can test this by refreshing the page multiple times — you should see different process.pid values in the response.

Clustering an Express App

Many Node.js apps use Express (or Fastify, or Koa) as the web framework.
Good news: the clustering approach is the same — just wrap your existing app inside the worker block. ✌️

Example: Clustered Express App

import cluster from 'cluster';
import os from 'os';
import express from 'express';

const numCPUs = os.cpus().length;

if (cluster.isPrimary) {
  console.log(`Primary process ${process.pid} is running`);
  console.log(`Forking ${numCPUs} workers...`);

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} exited. Restarting...`);
    cluster.fork();
  });

} else {
  const app = express();

  app.get('/', (req, res) => {
    res.send(`Hello from worker ${process.pid}`);
  });

  app.listen(3000, () => {
    console.log(`Worker ${process.pid} listening on port 3000`);
  });
}

Running It

npm run start-express

What Changed?

Instead of using http.createServer, each worker runs its own Express app.
The primary process still manages worker lifecycle.
Load balancing happens at the OS level — you don’t have to change your app logic.

Why It Works

👉 Each worker is a separate process with its own event loop and memory.
👉 The OS handles distributing incoming connections to available workers (via the cluster module’s internal use of shared socket).

Gotchas

⚠️ No shared in-memory state

If you store sessions or in-memory cache in the app, this won’t be shared between workers.
Use Redis / external store if you need shared state.

⚠️ More memory usage

Each worker is a full Node process → watch your server memory.

⚠️ Graceful shutdown is important

If you deploy new versions, make sure to gracefully shut down workers to avoid dropping connections.

Here’s a nice section 5️⃣ Conclusion + repo link block you can drop at the end of the post:

Conclusion

Clustering is one of those "easy to start, powerful to master" tools in the Node.js ecosystem.

👉 If your app needs to scale beyond a single CPU core, clustering can help you:

Improve throughput
Increase resiliency
Maximize your server’s hardware

👉 If your app is already distributed (via containers, load balancers, Kubernetes), clustering might be unnecessary — or even redundant.

👉 Remember: clustering doesn’t solve performance issues in your app itself — it helps your good app scale further.

📦 Full Example Repository

I’ve created a full example repo you can clone and experiment with:

👉 https://github.com/erickne/node-cluster 🚀

📂 Includes:

Simple HTTP server cluster
Express app cluster
Graceful shutdown pattern (bonus)
Minimal & production-friendly setup

That’s it — happy scaling!
If you enjoyed the post, give the repo a ⭐ and share it with your fellow devs.

And as always: don’t cluster just for the sake of it — cluster smart. 😉

Demystifying the Adapter Pattern

Erick Engelhardt — Fri, 30 May 2025 20:00:32 +0000

Ever tried plugging a USB-C into a micro-USB port? That’s exactly what the Adapter Pattern is here for. Not literally, but conceptually.

The Adapter Pattern is all about making incompatible interfaces work together. It acts like a bridge between two systems that weren’t designed to cooperate. You wrap one object with another that translates method calls and properties into a compatible format.

When Should You Use It?

You have legacy code that doesn't match your current interface.
You want to integrate third-party libraries with your own abstraction.
You're refactoring a codebase gradually and need backward compatibility.
You're dealing with multiple interfaces that perform similar but not identical functions.

This is especially useful in enterprise-scale projects where changing one system has ripple effects across many modules.

Real-World Example: Payments

Imagine you're switching payment providers. Your app was built using an older LegacyPayment class, but you want to move toward a new unified interface.

Step 1 - Legacy system and desired abstraction

export class LegacyPaymentSdk {
  sendPayment(amount: number) {
    console.log(`Paid $${amount} via LegacyPayment`);
  }
}

export class StripeSdk {
  charge(value: number, metadata: Record<string, any>) {
    console.log(`Charged $${value} via Stripe with metadata:`, metadata);
  }
}


export interface PaymentPayload {
  amount: number;
  payerName: string;
  payerEmail: string;
}

export interface PaymentProvider {
  pay(data: PaymentPayload): PaymentResult;
}

export interface PaymentResult {
  transactionId: string;
  success: boolean;
}

Step 2 - Adapters for each implementation

export class LegacyPaymentAdapter implements PaymentProvider {
  constructor(private legacy: LegacyPaymentSdk) {}

  pay(data: PaymentPayload): PaymentResult {
    console.log('Adapter translating pay() to sendPayment()');
    // Only amount is used; legacy gateway does not support metadata
    this.legacy.sendPayment(data.amount);
    return { transactionId: 'legacy-123', success: true }; // Simulated response
  }
}

export class StripeAdapter implements PaymentProvider {
  constructor(private stripe: StripeSdk) {}

  pay(data: PaymentPayload): PaymentResult {
    console.log('Adapter translating pay() to charge()');
    const metadata = {
      name: data.payerName,
      email: data.payerEmail
    };
    this.stripe.charge(data.amount, metadata);
    return { transactionId: 'stripe-456', success: true }; // Simulated response
  }
}

Step 3 - Service layer using the interface

export class PaymentService {
  constructor(private provider: PaymentProvider) {}

  handleCheckout(data: PaymentPayload): PaymentResult {
    console.log('Service initiating payment...');
    const result = this.provider.pay(data);
    console.log(`Service completed payment. Transaction ID: ${result.transactionId}, Success: ${result.success}`);
    return result;
  }
}

Step 4 - Usage with different adapters

const legacyAdapter = new LegacyPaymentAdapter(new LegacyPaymentSdk());
const stripeAdapter = new StripeAdapter(new StripeSdk());

const legacyService = new PaymentService(legacyAdapter);
const stripeService = new PaymentService(stripeAdapter);

legacyService.handleCheckout({
  amount: 100,
  payerName: 'Alice',
  payerEmail: 'alice@example.com'
});

stripeService.handleCheckout({
  amount: 200,
  payerName: 'Bob',
  payerEmail: 'bob@example.com'
});

Run the Example

yarn start

Full Output

1) Service initiating payment...
2) Adapter translating pay() to sendPayment()
3) Paid $100 via LegacyPayment
4) Service completed payment.

5) Service initiating payment...
6) Adapter translating pay() to charge()
7) Charged $200 via Stripe with metadata: { name: 'Bob', email: 'bob@example.com' }
8) Service completed payment.

Output Breakdown

LegacyPayment flow:

1) The PaymentService starts the legacy checkout process.
2) The adapter translates the call to match the legacy interface.
3) Payment is processed using the legacy gateway.
4) The service completes the first transaction.

Stripe flow:

5) Begins the second checkout using the Stripe adapter.
6) Adapter maps the unified method to Stripe’s method.
7) Payment succeeds, including user metadata.
8) Finalizes the second transaction.

Testing the Adapter Integration

The repository includes unit tests to ensure your service logic remains decoupled from any specific SDK or gateway.

The file payment.service.spec.ts uses a mocked version of the PaymentProvider interface to test the PaymentService independently.

This allows you to:

Fully isolate service behavior from real implementations
Guarantee contract compliance
Swap adapters without affecting test coverage

Run the Tests

yarn test

Test File: `payment.service.spec.ts`

This testing approach ensures your PaymentService can be reused anywhere, as long as a compatible adapter is injected.

This structure lets you plug and play with multiple providers without changing your business logic. Each adapter can include gateway-specific logic, such as formatting, validation, metadata conversion, retries, and so on.

If tomorrow you adopt another provider (like PayPal or Adyen), all you need is another adapter.

Benefits of the Adapter Pattern

Decoupling: Your core app logic is isolated from external or legacy systems.
Gradual migration: Swap internals behind the scenes without breaking public interfaces.
Consistency: Enforce a common API across different providers or modules.
Testability: Mock adapters in tests instead of actual implementations.
Extendability: Add logic to adapt not just method names but also data formatting, validation, or retries.

Common Pitfalls

Overuse: Don't use adapters as an excuse to skip proper refactoring.
Performance hit: Wrapping layers can introduce slight overhead.
Too much abstraction: Over-adapting might confuse new developers.

Use it where there's a real gap in compatibility, not as a blanket solution for all mismatches.

Pro Tips

Pair with Dependency Injection for even better separation of concerns.
Combine with Factory Pattern to automate the adapter selection logic.
Favor interfaces over concrete classes to increase flexibility.
Avoid adapting things that should just be rewritten. Sometimes adapters hide tech debt instead of solving it.

Adapters aren't glamorous, but they solve real-world messes. And let's be honest, clean architecture often comes down to choosing the right boring solution at the right time.

Check out a full working repo: https://github.com/erickne/ts-adapter-pattern

Forem: Erick Engelhardt

Scaling Your Node.js App: An Introduction to Clustering

How Does Node Work Under the Hood?

Why Cluster?

Benefits

Risks & Tradeoffs

When Should You Use Clustering?

Good Use Cases for Clustering

When NOT to Use Clustering

Rule of Thumb

Basic Example of Clustering in Node.js

Simple Cluster Example

How It Works:

Running It

Clustering an Express App

Example: Clustered Express App

Running It

What Changed?

Why It Works

Gotchas

Conclusion

📦 Full Example Repository

Demystifying the Adapter Pattern

When Should You Use It?

Real-World Example: Payments

Step 1 - Legacy system and desired abstraction

Step 2 - Adapters for each implementation

Step 3 - Service layer using the interface

Step 4 - Usage with different adapters

Run the Example

Full Output

Output Breakdown

Testing the Adapter Integration

Run the Tests

Test File: payment.service.spec.ts

Benefits of the Adapter Pattern

Common Pitfalls

Pro Tips

Test File: `payment.service.spec.ts`