Starter Kit Serverless Node

May 30, 2025 · View on GitHub

A production-ready serverless starter kit built with Hexagonal Architecture, featuring advanced patterns like Dependency Injection, Reactive Programming (RxJS), and comprehensive AWS PostgreSQL integration. This enterprise-grade template demonstrates modern TypeScript development practices in a serverless environment.

📌 Project Overview

This starter kit provides a robust foundation for building scalable microservices using clean architecture principles. It integrates AWS Lambda with PostgreSQL RDS Proxy, implements comprehensive validation and logging systems, and showcases advanced patterns like reactive programming and dependency injection in a serverless context.

Core Technologies: Node.js 22, TypeScript, AWS Lambda, PostgreSQL, RxJS, Inversify, Serverless Framework

Problem Solved: Bridges the gap between enterprise development patterns and serverless architecture, providing a maintainable, testable, and production-ready foundation for microservices development.

📁 Project Structure

├── src/
│   ├── constant/           # Application constants and DI symbols
│   ├── gateway/           # Infrastructure adapters (PostgreSQL, external services)
│   ├── handler/           # Lambda function handlers (API entry points)
│   ├── infrastructure/    # Core infrastructure (logging, errors, containers)
│   ├── middleware/        # Custom Middy middlewares (DB connection, validation)
│   ├── repository/        # Domain interfaces and contracts
│   ├── service/          # Business logic layer (domain services)
│   └── utils/            # Shared utilities and helper functions
├── schema/               # JSON Schema validation definitions
├── types/                # Auto-generated TypeScript type definitions
├── serverless.yml        # Serverless Framework configuration
└── ServerlessScripts.js  # Dynamic configuration scripts

🚀 Getting Started

Prerequisites

  • Node.js >= 22.x
  • AWS CLI configured with appropriate credentials
  • Serverless Framework installed globally
  • PostgreSQL RDS instance with RDS Proxy configured

Installation

# Clone the repository
git clone https://github.com/davidhernandez-adm/starter-kit-serverless-node.git
cd starter-kit-serverless-node

# Install dependencies
npm install

# Generate TypeScript types from JSON schemas
npm run types

Environment Setup

Configure the following environment variables in AWS Systems Manager Parameter Store:

# Parameter: /{service-name}/{stage}/SLS_BUILD
{
  "pgDbProxyEndpoint": "your-rds-proxy-endpoint",
  "pgDbUser": "your-db-username",
  "pgDbName": "your-database-name",
  "pgDbRegion": "us-east-1"
}

Development

# Run linting and formatting
npm run lint

# Run all tests with coverage
npm run test

# Validate code quality (lint + test)
npm run validate

# Deploy to AWS
USRV_STAGE=dev npm run deploy

Testing the API

# POST request to hello endpoint
curl -X POST https://your-api-gateway-url/starterkit/v1/hello \
  -H "Content-Type: application/json" \
  -d '{"name": "Developer"}'

# Response: "Hello Developer. [30-05-2025 14:30:00]"

📦 Technologies Used

Core Stack

  • TypeScript 5.7 - Type-safe development with advanced configurations
  • Node.js 22 - Latest LTS with ARM64 architecture support
  • AWS Lambda - Serverless compute with HTTP API integration
  • PostgreSQL - Primary database with RDS Proxy connection pooling
  • RxJS 7 - Reactive programming for asynchronous operations

Architecture & Patterns

  • Inversify 6 - Dependency injection container
  • Hexagonal Architecture - Clean separation of concerns
  • Repository Pattern - Data access abstraction
  • Reactive Programming - Event-driven asynchronous processing

Middleware & Validation

  • Middy 6 - Lambda middleware framework with multiple plugins
  • AJV - High-performance JSON Schema validation
  • JSON Schema - Request/response validation with auto-generated types

Development & Testing

  • Mocha + Chai + Sinon - Comprehensive testing framework
  • NYC - Code coverage reporting with threshold enforcement
  • ESLint + Prettier - Code quality and formatting
  • Husky + Lint-staged - Pre-commit hooks for quality gates

Infrastructure & Security

  • AWS RDS Signer - IAM-based database authentication
  • Custom ESBuild - Optimized bundling with ARM64 targeting
  • Serverless Framework 4 - Infrastructure as Code with canary deployments
  • AWS Systems Manager - Secure parameter management

🧪 Testing and Coverage

The project enforces 100% test coverage with comprehensive testing strategies:

# Run unit tests
npm run test:unit

# Generate coverage report
npm run test:coverage

# Validate coverage thresholds
npm run test:check-coverage

# Watch mode for development
npm run test:watch

Testing Features:

  • Unit Tests: Service layer business logic validation
  • Integration Tests: Database gateway and middleware testing
  • Mock Strategies: Sinon-based mocking for external dependencies
  • Coverage Enforcement: Automated quality gates preventing regression

🏗️ Architecture Highlights

  • Hexagonal Architecture: Clear boundaries between domain, application, and infrastructure layers
  • SOLID Principles: Demonstrates all five principles with practical implementations
  • Event-Driven Design: Reactive streams for handling asynchronous business logic
  • Security-First Approach: IAM authentication, data masking, and least-privilege principles
  • Observability Built-in: Comprehensive logging, error tracking, and request tracing
  • Type Safety: End-to-end type safety from API contracts to database queries

🚀 Production Features

  • Canary Deployments: Automated gradual rollouts with environment-specific strategies
  • Custom Domain Management: SSL certificate integration with Route53
  • Resource Tagging: Comprehensive cost tracking and resource organization
  • Log Retention Policies: Environment-specific retention strategies
  • Error Handling: Centralized error management with structured error responses
  • Performance Optimization: ARM64 architecture, connection reuse, and bundle optimization

📈 Performance Considerations

  • Cold Start Optimization: Dependency injection container optimization for Lambda initialization
  • Bundle Size: ESBuild configuration excluding AWS SDK, reducing package size by ~40%
  • Connection Pooling: Efficient PostgreSQL connection management with configurable timeouts
  • Memory Management: Careful resource cleanup and circular reference handling

🔄 CI/CD Integration

The project is designed for Buddy CI/CD with support for:

  • Feature Branch Testing: Automated integration testing
  • Stage Environment: Automatic deployment from develop branch
  • Production Deployment: Controlled releases from main branch
  • Dependency Caching: Optimized build times with node_modules caching

📜 License

MIT License - see LICENSE file for details.

Built with ❤️ using enterprise-grade serverless architecture and modern TypeScript patterns.