Write Microservices in Node.js: A Comprehensive Guide

Write Microservices in Node.js A Comprehensive Guide


Microservices architecture has become the de facto standard for building robust, scalable backend systems. Node.js with its asynchronous event-driven model is a great fit for implementing high-performance microservices.

This comprehensive guide covers:

  • Microservices architecture and benefits
  • Planning and modeling microservices
  • Building Node.js microservices using Hapi framework
  • Service discovery, routing and deployment patterns
  • Migration strategies from monolith to microservices

By the end, you’ll have practical understanding of architecting and developing microservices in Node.js.

Overview of Microservices

Microservices architecture structures backend systems as a collection of small autonomous services rather than one large monolithic application.

Each microservice focuses on a specific business domain or workflow and exposes a well defined API contract. Microservices communicate via lightweight protocols like HTTP resource APIs or events.

Why Microservices?

Comparing monolithic vs microservices architecture:

Service boundariesUnclearWell defined by service
Adaptability to changeRigidEvolve independent services
ScalingScale entire app tierScale specific high load services
ResilienceEntire system vulnerableIsolate failures to specific services
Code maintenanceComplex and risky deploysSimpler deploys for incremental changes
PerformanceOften lower due to increased loadOptimized by smarter service decomposition
Tech heterogeneityUniform tech stackFlexibility in languages, databases etc.
monolithic vs microservices architecture

Microservices unlock agility, scalability and velocity for rapidly evolving digital environments. Each service acts as a mini-application owning its domain while still coordinating to deliver end user workflows.

However, microservices also introduce complexity of distributed systems – network issues, resilience testing, database transactions spanning services etc. The approach warrants careful service modeling aligned with business needs before implementation.

Which brings us to…

Designing Microservices

Though microservices promise long term maintainability gains, they require upfront design investment to define service boundaries and interactions.

Pick Business Capabilities, Not Technologies

A common pitfall is defining services based on technical layers – user management service, notification service etc. Services should ideally map to business capabilities – identity, subscription management etc. This creates services aligned with changing business needs rather than transient technologies.

Bounded Contexts

Domain driven design (DDD) prescribes decomposing complex business domains into multiple bounded contexts, each mapping to a service owning specific domain logic.

For ecommerce, key bounded contexts could be:

  • Product domain – Inventory, pricing, catalog management functionality
  • Ordering domain – Shopping cart, order fulfillment logic
  • Payments domain – Payment, billing and revenue logic

This splits business capabilities across isolated services based on change patterns.

Granularity – Size It Right

Balance splitting complex domains across multiple services with efficiency of develop-to-deploy cycles and coordination overhead between services. Key factors influencing microservice granularity:

  • Business Capability Maturity: Stable business sub-domains can be isolated into separate services safely.
  • Organizational Structure: Align services with teams to simplify ownership.
  • Cost of coordination: Chatty interfaces between services add integration hassles – optimize based on interaction frequency.

Get the organizational change management and governance models right to drive effective adoption at large scale.

Define APIs, Events and Messages

Formalize how services can be consumed and interact early on. This acts as contract allowing services to evolve independently:

  • APIs – Specify REST, RPC endpoints providing service access
  • Events – Declare events published and subscribed to facilitate asynchronous, stateless messaging
  • Messages – Standard schemas for documents, commands exchanged via event streams

With domain modeling and contracts established, we can proceed to implementation.

Building MicroServices in Node.js

Node.js, with its asynchronous event-driven runtime optimized for I/O bound workloads, is great for high throughput and low latency microservices. Its lightweight and high scalability make it ideal for modern service architectures.

We’ll leverage Hapi, a popular Node.js web framework, for building services. Hapi promotes config driven development minimizing code through reusable components and plugin architecture.

Project Setup

Initialize a Hapi project using NPM:

mkdir products-service
cd products-service
npm init
npm install @hapi/hapi @hapi/inert @hapi/vision  
touch index.js

This scaffolds a barebones Hapi app with the web server and plugin dependencies.

Configure Hapi Server

Hapi promotes lots of configurability through registration of plugins, routes, parameters etc.

Let’s setup a basic Hapi 17+ app server.


'use strict';

const Hapi = require('@hapi/hapi'); 

const init = async () => {

  const server = Hapi.server({
    port: 3000,
    host: 'localhost',
    /* route config */
    /* register plugins */

  await server.start();
  console.log('Server running on %s', server.info.uri);

process.on('unhandledRejection', (err) => {


This creates a new Hapi server instance with host and port information, handling uncaught exceptions using event listeners.

Register Plugins

Hapi supports a rich plugin ecosystem to incorporate reusable functionality – auth, CORS, validation, caching etc. easily.

Let’s register some essential plugins:

await server.register([

This configures the joi validator for API parameter validation.

Add REST API Route Handler

With the foundation setup, we can start adding the key application logic – the API route handlers.

Let’s expose a basic health check ping endpoint:

  method: 'GET',
  path: '/health',
  handler: (request, h) => {
    return "I'm healthy!";

This leverages Hapi’s declarative routing to register a GET endpoint matching /health returning a string response.

Similarly, we can add multiple route handlers for resources like /products etc. with input validation, authentication and business logic.

Error Handling

It’s crucial to handle errors gracefully ensuring proper response codes and messaging to callers.

Hapi provides the Boom utility for signaling errors:

const Boom = require('@hapi/boom');

function getProduct(id) {
  if(!found) {
    throw Boom.notFound(`Product ${id} not found`); 

We can also register a global error handler to standardize error payloads:

const errorHandler = (request, h) => {
  // format error  
  return h.response().code(error.output.statusCode);

server.events.on('response', errorHandler);

This simplifies centralized handling across services.

Building the Docker Image

To containerize services for smooth portability across environments, we leverage Docker:


FROM node:18-alpine
WORKDIR /usr/src/app 
COPY . .
RUN npm install --production
CMD ["node", "index.js"]

This bundles app code with Node.js base image into an optimized container package ready for distribution:

docker build -t products-service . 
docker run -p 3000:3000 products-service

Each service can be deployed consistently from laptop to cloud this way.

This summarizes a basic workflow for developing robust services with Node + Hapi!

Deploying Microservices

While developing discrete services is a first step, real world usage warrants intelligent networking for efficient request routing, failover handling etc.

We explore proven architectural patterns:

Service Registry and Discovery

Hardcoding service hosts and ports leads to tight coupling. We need dynamic lookup of service instances. Solutions include:

Client Side Discovery

The calling client queries a service registry to find target service locations. Examples are Netflix Eureka, Consul service catalog.

Client => Service Registry => Target Service

Server Side Discovery

A router / proxy virtualizes actual service instances and forwards requests via dynamic routing tables. Examples are Envoy, Linkerd.

Client => API Gateway / Reverse Proxy => Target Service

This hides underlying location changes from consumers for seamless failovers.

Load Balancing

To scale horizontally, incoming requests need load balancing across multiple service instances. Strategies include:

Hardware LB – Use external load balancers like F5 or HAProxy.

Software LB – Tools like Nginx or Traefik forward requests among service backends.

Service Mesh – Infrastructure like Istio manages service-to-service traffic flows natively.

Production setups combine layers – Kubernetes Ingresses, Nginx, custom proxy routers etc.


Adding caching minimizes duplicate resource intensive operations. Tactics:

CDN Caching – Front cache entire application or assets in globally distributed CDNs.

API Caching – Cache backend API responses – key-value stores like Redis are popular.

Database Caching – Cache frequent DB queries in services via tools like Redis or Memcached.

Caching helps significantly improve performance, resilience and scalability.

Migrating from Monolith to Microservices

While starting microservices from scratch has simplicity, in reality there often is significant monolithic legacy system investment powering business functions. How do we smartly migrate piecemeal?

Incremental Rewrites

Legacy systems tend to be large entangled codebases grown organically over years without modularization – making full rewrite prohibitively expensive.

The key is rewriting parts incrementally:

  • Identify customer facing components like ecommerce frontend app as first area to migrate. This decouples public API quickly.
  • Next attack complex domains like payments, shipping which warrant isolation as services with dedicated teams.
  • Over time the monolith shrinks, delegating functionality to newer microservices exposing cleaner facades.

This makes migration manageable while allowing teams to keep innovating on isolated new services.

Strangling the Monolith

As legacy code frontrunning customer value, intermingled dependencies make extracting code tricky without impacting existing behaviors.

A pattern called branch by abstraction creates a parallel abstraction layer while still routing traffic to old implementation. Once new module is complete, traffic switches to it while old module whithers away (“strangled”).

For example, an Order Service wrappping existing order logic can be evolved independently. Once mature, integration points can route there instead.

This allows building new capabilities keeping legacy system unaware of ongoing modernization efforts until integration swap time.

No Full Rewrites

A common but risky anti pattern is attempting to engineer fully “future proof” versions upfront through large do-it-all projects attempting big bang switchovers. Chances are requirements evolve so much that these get outdated before being complete.

It is pragmatic to build modular pave-the-road-as-you-walk by isolating domains intelligently balancing business needs with technical approach instead of aiming for hypothetical utopia end states that tend to constantly shift anyway! This helps link migration tightly to tangible goals.

Going to Production

Once we have target services scoped out, leveraging robust deployment tooling and environments specifically tailored for modern infrastructures and microservices becomes vital:

  • Kubernetes – Orchestrator managing containers, load balancing, failover handling
  • CI/CD Pipelines – Automate container build, tests and promotions across envs
  • Monitoring – Telemetry for tracking services, setting alerts, dashboards
  • Chaos Testing – Induce failures to ensure system resilience
  • Service Mesh – Infrastructure layer managing secure communication, retries, tracing

Investment across above areas is essential for running microservices in production grade manner.

Wrapping Up

So in this guide, we walked through:

  • Why microservices – Comparing architecture styles
  • Modeling domains – Bounded contexts, right sized services
  • Implementing with Node + hapi – Simple yet powerful runtime + framework
  • Deployment patterns – Dynamic discovery, routing, scaling
  • Migrating monoliths – Transitioning prudently balancing incremental delivery with system coherence
  • Productionizing – Leveraging cloud native capabilities for observability, resilience and productivity

I hope this comprehensive yet accessible guide serves as helpful blueprint for embarking on your microservices modernization journey with Node.js. Let me know if any part needs more clarification!

Frequently Asked Questions

Q: When should you not use microservices?

For smaller apps with limited domains, microservices tend to add unnecessary overheads of distributed systems without significant benefits. Monoliths may work better for bounded use cases. Evaluate if benefits warrant complexity.

Q: How do you handle transactions across microservices?

ACID transactions difficult across microservices. Common pattern is eventual consistency via events/logs with compensating actions resolving inconsistencies and replaying as needed. Saga pattern can model long workflows. Database locks can help concurrent operations.

Q: Which types of tests are crucial for microservices?

Unit testing – Individual functions
Integration testing – Modules interacting with their direct dependencies
End to end testing – Simulate user journeys across full backend
Load testing – Stress test components
Chaos testing – Randomly fail parts to test robustness

Automated regression testing across above dimensions is critical given frequent changes.

Q: When deploying microservices on Kubernetes, what considerations are important?

Namespace segregation, network policies for access control,Tune resource quotas. Trace services using logs. Implement request timeouts, retries, circuit breakers. Handle DNS changes during failover. Replicate stateful services. Backup/restore data.

Q: How do you handle breaking API changes between microservice releases?

Use semantic versioning indicating compatibility breaks. Provide deprecation warnings before APIs undergo removal or changes. Maintain backward compatibility accepting old parameters while logging usage to gauge client adoption. Define policies around API evolution cadence, communication and support pipelines.

I hope these Q&A helps clarify some common microservice development and architecture concerns. Feel free to reach out for any additional questions!

Leave a Reply

Your email address will not be published. Required fields are marked *