NexusKit: The Complete Microservices Toolkit

A production-ready, enterprise-grade microservices toolkit built with NestJS and Nx. NexusKit provides a robust, scalable, and maintainable foundation for building distributed systems with built-in service discovery, load balancing, dynamic scaling, multi-tenancy support, and extensible libraries for CQRS, gRPC, GraphQL, resilience, and more.

🚀 Features

Core Architecture

🏗️ Monorepo Structure: Built with Nx for efficient development and build processes
🔍 Service Discovery: Automatic service registration and discovery using Consul or ZooKeeper
⚖️ Load Balancing: Intelligent load balancing with configurable strategies
🔄 Dynamic Scaling: Support for multiple instances of the same service with dynamic port allocation
🌐 HTTP Client: Declarative HTTP service clients with automatic service resolution
🔄 Health Checks: Built-in health monitoring with configurable timeouts
🛡️ Graceful Shutdown: Proper application lifecycle management
📊 Real-time Monitoring: Live service status and health tracking

Service Infrastructure

📡 Service Registry: Centralized service registration and management via Consul or ZooKeeper
🔧 Configuration Management: Flexible configuration loading from multiple sources
📊 Service Monitoring: Real-time service health and status tracking
🔄 Retry Mechanisms: Robust error handling with configurable retry policies
🎯 Metadata Management: Comprehensive service metadata and tagging system
🔄 Auto-scaling: Dynamic service instance management with load balancing

Development Experience

🔧 TypeScript First: Full TypeScript support with strict typing
📦 Modular Design: Clean separation of concerns with reusable libraries
🧪 Testing Ready: Built-in testing infrastructure with Jest
📝 Code Quality: ESLint and Prettier integration for consistent code style
🚀 Hot Reload: Development server with automatic reloading
🛠️ Management Scripts: Automated scripts for service lifecycle management

🏗️ Architecture Overview

This project follows a modular microservice architecture with the following key components:

├── apps/                    # Application services
│   ├── service-1/          # Example microservice 1 (port 3333)
│   └── service-2/          # Example microservice 2 (port 3334)
├── libs/                   # Shared libraries
│   ├── bootstrap/          # Configuration management
│   ├── client/             # HTTP client framework
│   ├── cloud/              # Cloud-native abstractions
│   ├── common/             # Shared utilities and interfaces
│   ├── consul/             # Service discovery and registry
│   ├── loadbalancer/       # Load balancing strategies
│   └── zookeeper/          # ZooKeeper service discovery and registry
├── scripts/                # Service management scripts
│   ├── start-service.sh    # Dynamic service startup
│   ├── stop-service.sh     # Service shutdown
│   ├── status.sh           # Service status monitoring
│   └── test-loadbalancer.sh # Load balancing tests

Key Libraries

@nexuskit/bootstrap: Configuration management with file-based loading
@nexuskit/client: Declarative HTTP service clients with service discovery
@nexuskit/cloud: Cloud-native service abstractions and registry management
@nexuskit/common: Shared utilities, interfaces, and common functionality
@nexuskit/consul: Consul integration for service discovery and health checks
@nexuskit/loadbalancer: Configurable load balancing with multiple strategies
@nexuskit/zookeeper: ZooKeeper integration for service discovery and registry

🛠️ Technology Stack

Component	Technology	Version
Runtime	Node.js	18+
Framework	NestJS	10.0+
Language	TypeScript	5.0+
Build System	Nx	17.0+
Service Registry	Consul/ZooKeeper	1.21+/3.8+
HTTP Client	Got	11.8.2
Testing	Jest	29.0+
Linting	ESLint	8.0+
Formatting	Prettier	3.0+

📦 Installation

Prerequisites

Node.js 18 or higher
npm or yarn package manager
Docker (for Consul)

Quick Start

Clone the repository

git clone https://github.com/your-username/mt-microservices-arch.git
cd mt-microservices-arch

Install dependencies
```
npm install
# or
yarn install
```

Start Service Registry (required for service discovery)

# Using Consul (recommended)
docker run -d --name consul -p 8500:8500 hashicorp/consul:latest

# Or using ZooKeeper
docker run -d --name zookeeper -p 2181:2181 zookeeper:3.8

# Or install locally
# Follow instructions at https://www.consul.io/docs/install or https://zookeeper.apache.org/doc/current/zookeeperStarted.html

Start the development servers

# Start all services
npm run start

# Start specific service
npm run start service-1
npm run start service-2

🚀 Usage

Dynamic Service Management

The project includes powerful scripts for managing multiple service instances:

Start Multiple Service Instances

# Start 3 instances of service-2 starting from port 3334
./scripts/start-service.sh service-2 3 3334

# Start 2 instances of service-1 starting from port 3333
./scripts/start-service.sh service-1 2 3333

# Start 1 instance of service-2 on default port 3334
./scripts/start-service.sh service-2

Monitor Service Status

# Check all services
./scripts/status.sh

# Check specific service
./scripts/status.sh service-2

Test Load Balancing

# Test load balancing for service-2 with 10 requests
./scripts/test-loadbalancer.sh service-2 10

# Test load balancing for service-1 with 5 requests
./scripts/test-loadbalancer.sh service-1 5

Test ZooKeeper Integration

# Test ZooKeeper service discovery and registration
./scripts/test-zookeeper.sh

Stop Services

# Stop all service-2 instances
./scripts/stop-service.sh service-2

# Stop all service-1 instances
./scripts/stop-service.sh service-1

Creating a New Service

Generate a new service using Nx

npx nx generate @nx/nest:application my-service

Configure the service module

import { Module } from '@nestjs/common';
import { BootstrapModule } from '@nexuskit/bootstrap';
import { ClientModule } from '@nexuskit/client';
import { CloudModule } from '@nexuskit/cloud';
import { ConsulModule } from '@nexuskit/consul';
import { ZookeeperModule } from '@nexuskit/zookeeper';
import { LoadBalancerModule } from '@nexuskit/loadbalancer';

@Module({
  imports: [
    BootstrapModule.forRoot(),
    // Using Consul
    ConsulModule.forRoot({
      host: 'localhost',
      port: '8500',
      promisify: true,
      secure: false,
    }),
    // Or using ZooKeeper
    ZookeeperModule.forRoot({
      host: 'localhost:2181',
      retryAttempts: 6000,
    }),
    CloudModule.forRoot({
      registry: {
        discoverer: 'consul', // or 'zookeeper'
        service: {
          name: 'my-service',
          address: 'localhost',
          port: parseInt(process.env.PORT) || 3000,
        },
        discovery: {
          type: 'http',
          http: `http://192.168.1.201:${process.env.PORT || 3000}/api/health`,
          interval: 10,
          timeout: '5s',
          failFast: false,
          scheme: 'http',
        },
        heartbeat: {
          enabled: false,
          ttlInSeconds: 30,
        },
      },
    }),
    ClientModule.forRoot(),
    LoadBalancerModule.forRoot(),
  ],
})
export class AppModule {}

Using HTTP Service Clients

import { Controller, Get } from '@nestjs/common';
import { HttpClient, HttpServiceClient } from '@nexuskit/client';

@Controller()
export class AppController {
  @HttpServiceClient('service-2', {
    timeout: 5000, // 5 second timeout
    retry: 2, // retry 2 times
  })
  serviceInstance: HttpClient;

  @Get('/service-2')
  async getServiceData() {
    try {
      const svcData = await this.serviceInstance.get('api/');
      return svcData.body;
    } catch (error) {
      return {
        error: 'Service-2 is not available',
        message: error.message,
        timestamp: new Date().toISOString(),
      };
    }
  }
}

Configuration Management

Create a bootstrap.yaml file in your service directory:

config:
  service:
    name: 'My Service'

🔧 Configuration

Environment Variables

Variable	Description	Default
`PORT`	Service port	3333
`NODE_ENV`	Environment	development
`CONSUL_HOST`	Consul host	localhost
`CONSUL_PORT`	Consul port	8500
`ZOOKEEPER_HOST`	ZooKeeper host	localhost
`ZOOKEEPER_PORT`	ZooKeeper port	2181

Service Configuration

Each service can be configured through:

Environment variables
Bootstrap configuration files (bootstrap.yaml, bootstrap.json)
Runtime configuration injection

Health Check Configuration

discovery: {
  type: 'http',
  http: `http://192.168.1.201:${process.env.PORT || 3333}/api/health`,
  interval: 10,        // Check every 10 seconds
  timeout: '5s',       // 5 second timeout
  failFast: false,     // Don't fail fast on health check failure
  scheme: 'http',
}

🧪 Testing

Unit Tests

# Run all tests
npm run test

# Run tests for specific service
npm run test service-1

# Run e2e tests
npm run e2e

# Run affected tests
npm run affected:test

Load Balancing Tests

# Test load balancing with multiple instances
./scripts/test-loadbalancer.sh service-2 20

# Expected output shows requests distributed across instances:
# Request 1: abc123 (port 3334)
# Request 2: def456 (port 3335)
# Request 3: abc123 (port 3334)
# ...

📊 Monitoring and Health Checks

The framework provides comprehensive health monitoring:

Service Health: Automatic health check registration with Consul
Dynamic Timeouts: Configurable health check timeouts (5s default)
Service Discovery: Real-time service availability tracking
Load Balancer Health: Health-aware load balancing across instances
Instance Monitoring: Individual instance health tracking

Health Check Endpoints

Each service automatically exposes a health endpoint:

# Check service health
curl http://localhost:3333/api/health
# Response: {"status":"ok","timestamp":"2025-07-05T00:30:00.000Z"}

# Check service-2 health
curl http://localhost:3334/api/health
# Response: {"status":"ok","timestamp":"2025-07-05T00:30:00.000Z"}

Service Registry Health Monitoring

Consul Health Monitoring

# View all services in Consul
curl http://localhost:8500/v1/agent/services | jq

# View health checks
curl http://localhost:8500/v1/agent/checks | jq

# View healthy service instances
curl "http://localhost:8500/v1/health/service/service-2?passing=true" | jq

ZooKeeper Health Monitoring

# View all services in ZooKeeper
docker exec zookeeper zkCli.sh -server localhost:2181 ls /swft-mt-service

# View service details
docker exec zookeeper zkCli.sh -server localhost:2181 get /swft-mt-service/service__service-2__1.0.0-<uuid>

# View service instances
docker exec zookeeper zkCli.sh -server localhost:2181 ls /swft-mt-service/service__service-2__1.0.0-<uuid>

🔒 Security

Graceful Shutdown: Proper signal handling and cleanup
Error Handling: Comprehensive error handling with retry mechanisms
Service Isolation: Service-level isolation and security boundaries
Configuration Security: Secure configuration management
Health Check Security: Configurable health check endpoints

🚀 Production Deployment

Docker Deployment

# Build services
npx nx build service-1
npx nx build service-2

# Run with Docker Compose
docker-compose up -d

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: service-1
spec:
  replicas: 3
  selector:
    matchLabels:
      app: service-1
  template:
    metadata:
      labels:
        app: service-1
    spec:
      containers:
        - name: service-1
          image: your-registry/service-1:latest
          ports:
            - containerPort: 3333
          env:
            - name: PORT
              value: '3333'

🤝 Contributing

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

Development Setup

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Code Style

This project uses:

ESLint for code linting
Prettier for code formatting
TypeScript strict mode
Conventional commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Documentation: Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions

🙏 Acknowledgments

NestJS - Progressive Node.js framework
Nx - Build system with first-class support for many frontend and backend technologies
Consul - Service mesh solution providing a full featured control plane
ZooKeeper - Distributed coordination service for distributed applications
TypeScript - Typed JavaScript at scale

Built with ❤️ for the microservices community

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
apps		apps
libs		libs
patches		patches
scripts		scripts
tools		tools
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
README.md		README.md
jest.config.ts		jest.config.ts
jest.preset.js		jest.preset.js
nx.json		nx.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

puneetkakkar/nexuskit

Folders and files

Latest commit

History

Repository files navigation