nestjs-context

Useful nestjs libs using AsyncLocalStorage.

Overview

This monorepo provides useful libraries for NestJS applications, leveraging AsyncLocalStorage for advanced context management and instrumentation. It is designed to support a variety of production and advanced use cases, and will grow to include more libraries over time.

📦 Packages

`newrelic-nestjs-instrumentation`

Comprehensive New Relic instrumentation for NestJS applications with advanced transaction management, distributed tracing, and event-driven monitoring.

Key Features:

✅ Controller-based Transaction Management - Automatic transaction creation and context management
✅ Message Queue Instrumentation - SQS, Kafka, and custom queue consumers
✅ HTTP/2 Compatibility - Works with modern HTTP/2 applications
✅ Background Job Tracing - Cron jobs, scheduled tasks, and async workers
✅ Distributed Tracing - Cross-service transaction correlation
✅ Event-Driven Monitoring - Real-time transaction lifecycle events
✅ Async Context Preservation - Maintains transaction context across async operations
✅ Custom Transaction Naming - Based on controller and handler names

Installation:

npm install newrelic-nestjs-instrumentation
# or
pnpm add newrelic-nestjs-instrumentation

Quick Start:

import { Module } from '@nestjs/common';
import { NestJsNewrelicInstrumentationModule } from 'newrelic-nestjs-instrumentation';

@Module({
  imports: [NestJsNewrelicInstrumentationModule],
})
export class AppModule {}

🏗️ Monorepo Architecture

This project uses a modern monorepo setup optimized for development efficiency and CI/CD automation.

Tech Stack

📦 Package Manager: pnpm - Fast, disk space efficient package manager
🚀 Build System: Turbo - High-performance build system for JavaScript/TypeScript monorepos
🧪 Testing: Jest - Comprehensive testing framework with coverage reporting
📏 Code Quality: ESLint + Prettier - Linting and formatting
📝 Commit Standards: Commitlint - Conventional commit message validation
🔄 Git Hooks: Husky - Pre-commit and pre-push validation
🏷️ Release Management: Automated semantic versioning and publishing

Project Structure

nestjs-context/
├── .github/
│   └── workflows/          # GitHub Actions CI/CD pipelines
├── libs/                   # Package libraries (add your own!)
│   ├── newrelic-nestjs-instrumentation/
│   └── otel-nestjs-instrumentation/
├── scripts/                # Build and utility scripts
├── .husky/                 # Git hooks
├── .jest/                  # Jest configuration
├── turbo.json              # Turbo build configuration
├── pnpm-workspace.yaml     # pnpm workspace configuration
├── commitlint.config.js    # Commit message rules
└── package.json            # Root package configuration

🛠️ Development

Prerequisites

Node.js >= 22
pnpm >= 10.12.4
Git

Getting Started

Clone the repository

git clone https://github.com/codibre/nestjs-context.git
cd nestjs-context

Install dependencies
```
pnpm install
```
Run tests
```
pnpm test
```
Build packages
```
pnpm build
```

Development Commands

# Build all packages
pnpm build

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:cov

# Lint all packages
pnpm lint

# Auto-fix linting issues
pnpm lint:fix

# Format code
pnpm prettier:fix

# Validate commit messages
pnpm commit:validate

💡 Development Tip: Don't Worry About Formatting While Coding!

Focus on your logic, not formatting while developing. The project has automated tools to handle code style:

# After writing your code, run this to fix all formatting/linting issues:
pnpm lint:fix

This command will automatically:

✅ Fix ESLint rule violations
✅ Format code with Prettier
✅ Organize imports
✅ Remove unused variables
✅ Apply consistent code style

Pre-commit hooks will also run these fixes automatically when you commit, so you can stay in the flow of coding without interruption!

Code Quality Standards

TypeScript

Strict TypeScript configuration
Comprehensive type definitions
TSDoc documentation for all public APIs

Testing

Unit Tests: All business logic and utilities
Integration Tests: Real HTTP request testing with spies
Coverage: Maintained above 80%
Test Structure: Descriptive names, success/error scenarios

Commit Convention

We use Conventional Commits:

# Examples
feat(newrelic): add support for HTTP/2 instrumentation
fix(events): resolve memory leak in event emitter
docs(readme): update installation instructions
test(guard): add integration tests for transaction context

Commit Types:

feat: New features
fix: Bug fixes
docs: Documentation changes
test: Test additions or modifications
refactor: Code refactoring
perf: Performance improvements
chore: Build process or auxiliary tool changes

🚀 CI/CD & Publishing

Automated Publishing

The monorepo uses intelligent change detection to automatically:

Detect Changed Packages: Only builds and tests packages that have changes
Semantic Versioning: Automatically bumps versions based on conventional commits
Automated Publishing: Publishes to npm registry when changes are merged to main
Release Notes: Generates changelogs from commit messages

GitHub Actions Workflow

# Automatically triggers on:
# - Pull requests (run tests)
# - Push to main (run tests + publish if needed)
# - Manual dispatch (force publish)

Pipeline Steps:

Setup: Node.js, pnpm, dependencies
Build: Compile TypeScript, generate types
Test: Unit tests, integration tests, coverage
Lint: Code style and formatting checks
Publish: Automatic npm publishing for changed packages

Release Process

Releases are fully automated:

Commit Changes: Using conventional commit format
Create PR: CI runs all tests and checks
Merge to Main: Automatic version bump and publishing
Monitor: Check npm and GitHub releases

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork & Clone

# Fork on GitHub, then clone your fork
git clone https://github.com/your-username/nestjs-context.git
cd nestjs-context

2. Create Feature Branch

git checkout -b feat/your-feature-name

3. Development Workflow

# Install dependencies
pnpm install

# Make your changes
# Add tests for new functionality
# Update documentation

# Validate your changes
pnpm build
pnpm test
pnpm lint

4. Commit & Push

# Use conventional commit format
git add .
git commit -m "feat(scope): description of your changes"
git push origin feat/your-feature-name

5. Create Pull Request

Provide clear description of changes
Link any related issues
Ensure all CI checks pass

Pull Request Checklist

Code follows style guidelines
Tests pass locally
New functionality has tests
Documentation is updated
Commit messages follow conventional format
No breaking changes (or properly documented)

📋 Adding New Features

For New Instrumentation Types

Identify Use Case: What isn't covered by existing instrumentation?
Design Solution: Integration with existing components vs. new components
Implement with Tests: Comprehensive unit and integration tests
Documentation: Update README, add examples, document APIs

For Bug Fixes

Reproduce Issue: Create test demonstrating the bug
Fix Minimally: Smallest change to resolve the issue
Test Thoroughly: Verify fix + full test suite + edge cases

🔧 Package Development

Adding a New Package

Create Package Directory

mkdir libs/your-new-package
cd libs/your-new-package

Package Configuration

# Create package.json with proper workspace config
# Add to pnpm-workspace.yaml
# Configure turbo.json for build pipeline

Development Setup

# Add scripts in turbo.json
# Configure Jest for testing
# Set up TypeScript configuration

Testing Integration

Use --runInBand for consistent test execution
Mock external dependencies (New Relic, databases, etc.)
Test both success and error scenarios
Maintain high coverage (>80%)

📄 License

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

🌟 Support

Documentation: Check package-specific READMEs in libs/
Issues: GitHub Issues
Discussions: GitHub Discussions

🚀 Why Choose This Library?

Production Ready

✅ Battle-tested in high-traffic production environments
✅ Comprehensive testing with >90% coverage
✅ Performance optimized with minimal overhead
✅ Error resilient with graceful degradation

Developer Experience

✅ TypeScript first with complete type definitions
✅ Easy integration with minimal configuration
✅ Extensive documentation with real-world examples
✅ Active maintenance with regular updates

Enterprise Features

✅ Distributed tracing across microservices
✅ Custom transaction naming for better monitoring
✅ Event-driven architecture for real-time insights
✅ Background job instrumentation for complete visibility

Built with ❤️ by Codibre

Name		Name	Last commit message	Last commit date
Latest commit History 210 Commits
.github		.github
.husky		.husky
libs		libs
scripts		scripts
.editorconfig		.editorconfig
.gitignore		.gitignore
.lintstagedrc		.lintstagedrc
.npmrc		.npmrc
.prettierrc		.prettierrc
.release-it.base.json		.release-it.base.json
README.md		README.md
commitlint.config.js		commitlint.config.js
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json

codibre/nestjs-context

Folders and files

Latest commit

History

Repository files navigation