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:

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:

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