uwestjs

v2.0.1

Published

5 months ago

High-performance platform adapter (HTTP & WebSocket) for NestJS using uWebSockets.js

uWestJS

High-performance HTTP and WebSocket platform adapter for NestJS using uWebSockets.js

uWestJS is a high-performance platform adapter for NestJS, powered by uWebSockets.js. It provides both HTTP and WebSocket capabilities with significantly better performance while maintaining full compatibility with NestJS decorators and patterns you already know.

Why uWestJS?

uWebSockets.js is one of the fastest HTTP and WebSocket implementations available, offering:

Up to 4-5x faster than Express and Fastify
Lower memory footprint for handling thousands of concurrent connections
Native backpressure handling to prevent memory issues under load
Built-in compression support for reduced bandwidth usage
Streaming support with automatic backpressure management

uWestJS brings this performance to NestJS without requiring you to change your existing code.

Documentation

WebSocket Documentation

Adapter - UwsAdapter configuration and methods
Socket API - UwsSocket properties and methods
Broadcasting - BroadcastOperator and broadcasting patterns
Decorators - NestJS WebSocket decorators
Rooms - Room operations and patterns
Middleware - Guards, Pipes, and Filters
Exceptions - WsException and error handling
Lifecycle - Gateway lifecycle management

HTTP Documentation

Server - Server setup and configuration
Request - HTTP request object and methods
Response - HTTP response object and methods
Routing - Route registration and path parameters
Middleware - Guards, Pipes, Filters, and Interceptors
Body Parsing - JSON, form data, and more
Multipart - File uploads and multipart forms
Compression - Request/response compression
CORS - Cross-origin resource sharing
Static Files - Static file serving

Features

HTTP Features

High Performance - Up to 4-5x faster than Express and 2-2.5x than Fastify for HTTP requests → Server Documentation
Request Handling - Full Express-compatible request API with body parsing, headers, cookies, and more → Request API
Response Handling - Comprehensive response methods including streaming, compression, and caching → Response API
Routing - Path parameters, wildcards, and route registration → Routing Guide
Body Parsing - Automatic parsing for JSON, URL-encoded, multipart, raw, and text → Body Parsing
File Uploads - Multipart form data and file upload handling → Multipart Guide
Static Files - Advanced static file serving with caching, range requests, and ETag support → Static Files
Middleware - Full support for Guards, Pipes, Filters, and Interceptors → HTTP Middleware
Compression - Request and response compression support → Compression
CORS - Flexible cross-origin resource sharing configuration → CORS Configuration

WebSocket Features

NestJS Compatibility - Full support for @SubscribeMessage, @MessageBody, @ConnectedSocket decorators → Decorators
Room Management - Efficient room-based broadcasting and client organization → Rooms Guide
Broadcasting - Powerful broadcasting operators for targeted message distribution → Broadcasting
Middleware Support - Guards, Pipes, and Filters for WebSocket handlers → WebSocket Middleware
Lifecycle Management - Gateway lifecycle hooks and connection management → Lifecycle
Exception Handling - WsException and error handling patterns → Exceptions
Backpressure Handling - Automatic message queuing when clients are slow
CORS Configuration - Built-in CORS support for WebSocket connections
Compression - Per-message deflate compression support

General Features

TypeScript Support - Full type definitions and TypeScript-first design
Dependency Injection - Full NestJS DI support for all middleware
Shared or Separate Ports - Run HTTP and WebSocket on the same port or separate ports
Production Ready - Comprehensive test coverage and battle-tested in production

Installation

npm install uwestjs

Or using yarn:

yarn add uwestjs

Or using pnpm:

pnpm add uwestjs

Requirements

Node.js 24 or 25
NestJS >= 11.0.0
TypeScript >= 6.0.0

Note

Supported Node.js versions: 24, 25
If you experience installation or runtime issues, run npm cache clean --force before installing

Quick Start

HTTP Server

import { NestFactory } from '@nestjs/core';
import { UwsPlatformAdapter } from 'uwestjs';
import { AppModule } from './app.module';

async function bootstrap() {
  const adapter = new UwsPlatformAdapter();
  const app = await NestFactory.create(AppModule, adapter);
  
  await app.init();
  adapter.listen(3000, () => {
    console.log('HTTP server running on port 3000');
  });
}
bootstrap();

See Server Documentation for detailed setup instructions.

WebSocket Server

import { NestFactory } from '@nestjs/core';
import { UwsAdapter } from 'uwestjs';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  const adapter = new UwsAdapter(app, { port: 8099 });
  app.useWebSocketAdapter(adapter);
  
  // Replace YourGateway with your actual gateway class
  const gateway = app.get(YourGateway);
  adapter.registerGateway(gateway);
  
  await app.listen(3000);
}
bootstrap();

See Adapter Documentation for detailed setup instructions.

HTTP + WebSocket (Shared Port)

import { NestFactory } from '@nestjs/core';
import { UwsPlatformAdapter, UwsAdapter } from 'uwestjs';
import { AppModule } from './app.module';

async function bootstrap() {
  const httpAdapter = new UwsPlatformAdapter();
  const app = await NestFactory.create(AppModule, httpAdapter);
  
  const wsAdapter = new UwsAdapter(app, { 
    uwsApp: httpAdapter.getHttpServer(),
    path: '/ws'
  });
  app.useWebSocketAdapter(wsAdapter);
  
  // Replace YourGateway with your actual gateway class
  const gateway = app.get(YourGateway);
  wsAdapter.registerGateway(gateway);
  
  await app.init();
  httpAdapter.listen(3000, () => {
    console.log('HTTP and WebSocket running on port 3000');
  });
}
bootstrap();

See Server Documentation for more deployment patterns.

Configuration

HTTP Configuration

Configure the HTTP platform adapter with SSL, compression, and more:

const adapter = new UwsPlatformAdapter({
  key_file_name: 'key.pem',
  cert_file_name: 'cert.pem',
});

See Server Documentation for all configuration options.

WebSocket Configuration

Configure the WebSocket adapter with compression, timeouts, CORS, and more:

import { SHARED_COMPRESSOR } from 'uwestjs';

const adapter = new UwsAdapter(app, {
  port: 8099,
  path: '/ws',
  maxPayloadLength: 16384,
  idleTimeout: 60,
  compression: SHARED_COMPRESSOR,
  cors: {
    origin: 'https://example.com',
    credentials: true,
  },
});

See Adapter Documentation for all configuration options.

CORS Configuration

Both HTTP and WebSocket support flexible CORS configuration:

Specific origins (recommended for production)
Multiple origins
Dynamic origin validation
Credentials support

See HTTP CORS and Adapter Documentation for details.

Middleware Configuration

Enable dependency injection for Guards, Pipes, and Filters:

import { ModuleRef } from '@nestjs/core';

const moduleRef = app.get(ModuleRef);
const adapter = new UwsAdapter(app, {
  port: 8099,
  moduleRef, // Auto-wrapped internally
});

See HTTP Middleware and WebSocket Middleware for usage patterns.

Usage Guides

HTTP Usage

Request Handling - Access headers, query params, body, cookies
Response Methods - Send JSON, HTML, files, streams
Routing - Define routes with path parameters
Body Parsing - Parse JSON, form data, multipart
File Uploads - Handle file uploads
Static Files - Serve static assets
Middleware - Use Guards, Pipes, Filters, Interceptors
Compression - Enable compression
CORS - Configure cross-origin requests

WebSocket Usage

Decorators - Use @SubscribeMessage, @MessageBody, @ConnectedSocket
Rooms - Organize clients into rooms
Broadcasting - Send messages to multiple clients
Middleware - Use Guards, Pipes, Filters
Lifecycle - Handle connection/disconnection events
Exceptions - Handle errors gracefully

API Reference

UwsPlatformAdapter API - HTTP platform adapter methods
UwsAdapter API - WebSocket adapter methods
UwsSocket API - Socket instance methods
BroadcastOperator API - Broadcasting methods
Request API - HTTP request methods
Response API - HTTP response methods

Migration Guides

From Express

Key differences when migrating from Express:

Use UwsPlatformAdapter instead of Express adapter
Initialize with app.init() then adapter.listen() instead of app.listen()
Most Express APIs work the same (req, res, middleware)

See Server Documentation for detailed migration guide.

From Socket.IO

Key differences when migrating from Socket.IO adapter:

Use UwsAdapter instead of IoAdapter
Register gateways with adapter.registerGateway(gateway)
All NestJS decorators work the same way

See Adapter Documentation for detailed migration guide.

Performance

uWestJS provides significant performance improvements:

HTTP: Up to 4-5x faster than Express and 2-2.5x than Fastify
WebSocket: Much faster than traditional JS based Socket.IO
Memory: Lower memory footprint for concurrent connections
Backpressure: Automatic handling prevents memory issues
Compression: Built-in support reduces bandwidth usage

For performance tips and benchmarks, see Server Documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Testing

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Run tests with coverage
npm run test:cov

# Run tests in watch mode
npm run test:watch

Benchmarks

uWestJS delivers exceptional performance compared to traditional Node.js frameworks:

| Scenario | Express req/s | Fastify req/s | uWestJS req/s | Express throughput | Fastify throughput | uWestJS throughput | uWestJS vs Express | uWestJS vs Fastify | | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | | compression | 21.47k | 11.75k | 24.40k | 11.28 MB/s | 6.02 MB/s | 11.22 MB/s | 1.14x | 2.08x | | headers | 51.45k | 83.36k | 116.87k | 9.57 MB/s | 15.58 MB/s | 18.39 MB/s | 2.27x | 1.40x | | hello-world | 54.97k | 85.83k | 138.49k | 9.12 MB/s | 14.41 MB/s | 13.74 MB/s | 2.52x | 1.61x | | json-response | 51.11k | 79.57k | 113.99k | 13.94 MB/s | 21.78 MB/s | 27.83 MB/s | 2.23x | 1.43x | | mixed-response | 51.62k | 79.64k | 112.89k | 11.91 MB/s | 18.46 MB/s | 22.82 MB/s | 2.19x | 1.42x | | post-json | 45.23k | 39.57k | 79.88k | 8.37 MB/s | 10.79 MB/s | 13.56 MB/s | 1.77x | 2.02x | | query-params | 41.64k | 79.31k | 121.08k | 9.17 MB/s | 17.55 MB/s | 16.28 MB/s | 2.91x | 1.53x | | route-params | 49.30k | 78.81k | 116.46k | 11.24 MB/s | 18.04 MB/s | 23.21 MB/s | 2.36x | 1.48x | | static-file | 57.16k | 70.95k | 107.60k | 567.34 MB/s | 703.25 MB/s | 1.04 GB/s | 1.88x | 1.52x | | streaming-upload | 324.32 | 324.09 | 338.69 | 72.21 KB/s | 67.73 KB/s | 65.49 KB/s | 1.04x | 1.05x |

Test Environment:

CPU: AMD Ryzen 9 8945HS (8 cores / 16 threads, base ~4.0 GHz)
RAM: 16 GB
OS: Ubuntu 24.04 (native)
Node.js: v24.12.0
Duration: 20s per scenario

Run benchmarks yourself:

# Quick benchmark (10s per scenario)
npm run benchmark:quick

# Full benchmark (20s per scenario, saves results)
npm run benchmark

# Test benchmark setup
npm run benchmark:test

Or from the benchmarks directory:

cd benchmarks
npm install
npm run benchmark:quick

See benchmarks/README.md for detailed information about metrics collected, historical tracking, and CI/CD integration.

License

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

Acknowledgments

Built on top of uWebSockets.js
Designed for NestJS
Inspired by the NestJS community's need for high-performance WebSocket solutions

Support

GitHub Issues: Report a bug
GitHub Discussions: Ask questions

Author

Vikram Aditya

Organization

Part of FOSS FORGE