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';asyncfunctionbootstrap(){constadapter=newUwsPlatformAdapter();constapp=awaitNestFactory.create(AppModule,adapter);awaitapp.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';asyncfunctionbootstrap(){constapp=awaitNestFactory.create(AppModule);constadapter=newUwsAdapter(app,{port: 8099});app.useWebSocketAdapter(adapter);// Replace YourGateway with your actual gateway classconstgateway=app.get(YourGateway);adapter.registerGateway(gateway);awaitapp.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';asyncfunctionbootstrap(){consthttpAdapter=newUwsPlatformAdapter();constapp=awaitNestFactory.create(AppModule,httpAdapter);constwsAdapter=newUwsAdapter(app,{uwsApp: httpAdapter.getHttpServer(),path: '/ws'});app.useWebSocketAdapter(wsAdapter);// Replace YourGateway with your actual gateway classconstgateway=app.get(YourGateway);wsAdapter.registerGateway(gateway);awaitapp.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:

constadapter=newUwsPlatformAdapter({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';constadapter=newUwsAdapter(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';constmoduleRef=app.get(ModuleRef);constadapter=newUwsAdapter(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:

1. Use UwsPlatformAdapter instead of Express adapter
2. Initialize with app.init() then adapter.listen() instead of app.listen()
3. 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:

1. Use UwsAdapter instead of IoAdapter
2. Register gateways with adapter.registerGateway(gateway)
3. 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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

Links

• GitHub Repository
• npm Package
• NestJS Documentation
• uWebSockets.js