ultimate-ws

library2.0.9jsnpmunverified

Ultimate WS is a drop-in replacement for the 'ws' WebSocket library, built on top of uWebSockets.js for significantly higher performance. Current stable version is 2.0.9, released with an active maintenance cadence. Key differentiators include: same API as 'ws' but ~3.7x higher send rate in benchmarks, seamless integration with Ultimate Express, support for stand-alone server, existing uWS server, and HTTPS. Requires Node.js >=20. Ships TypeScript definitions. It is useful for projects wanting to migrate from 'ws' to uWebSockets without changing code, or for those using Ultimate Express for HTTP upgrades.

devops messaging

npm install ultimate-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ULTIMATE-WS

ultimate-ws

devopsjavascriptv2.0.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WebSocketServer

✓ import { WebSocketServer } from 'ultimate-ws'

✗ const WebSocketServer = require('ultimate-ws').WebSocketServer

Package supports both ESM and CJS. Use named import for WebSocketServer.

WebSocket

✓ import { WebSocket } from 'ultimate-ws'

✗ const ws = require('ultimate-ws')

WebSocket class is exported as a named export, not default.

createWebSocketStream

✓ import { createWebSocketStream } from 'ultimate-ws'

Available for compatibility with 'ws' stream API. Not commonly used.

Creates a standalone WebSocket server on port 3000 that echoes incoming messages.

import { WebSocketServer } from 'ultimate-ws'; const wss = new WebSocketServer({ port: 3000 }); wss.on('connection', (ws) => { ws.on('message', (message) => { ws.send(message); // echo }); }); console.log('WebSocket server running on ws://localhost:3000');

Debug

Known issues

gotchaWhen using with Ultimate Express, do NOT create an http server manually; instead pass the Ultimate Express app as 'server' option to WebSocketServer.

fix

Use new WebSocketServer({ server: ultimateExpressApp })

affects: >=1.0.0

breakingRequires Node.js >=20. Older Node versions are not supported.

fix

Upgrade Node.js to version 20 or later.

affects: >=2.0.0

gotchaThe 'WebSocket' constructor from 'ws' (client-side) is not provided; this package is server-only.

fix

Use a browser WebSocket or 'ws' client for client connections.

affects: >=1.0.0

deprecatedThe 'noServer' option from 'ws' is not supported; use 'server' option instead.

fix

Pass an existing server (uWS app or Ultimate Express app) via 'server' option.

affects: >=1.0.0

gotchauWebSockets.js is a native addon; installation may fail on unsupported platforms.

fix

Ensure your platform is supported by uWebSockets.js (Linux, macOS, Windows) and have build tools installed.

affects: >=1.0.0

Errors

Common errors & fixes

Error: The module 'uWebSockets.js' could not be found or built.

uWebSockets.js native addon requires compilation; missing build tools or unsupported platform.

fix

Install build-essential (Linux) or Visual Studio Build Tools (Windows). Alternatively, use a prebuilt binary.

TypeError: WebSocketServer is not a constructor

Using incorrect import (e.g., default import instead of named import) in CommonJS.

fix

Use const { WebSocketServer } = require('ultimate-ws') or named ESM import.

Error: listen EADDRINUSE :::3000

Port already in use by another server.

fix

Choose a different port or kill the process using the port.

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'ultimate-ws'

Package not installed or missing in node_modules.

fix

Run 'npm install ultimate-ws'

Upgrade

Version history

2.0.9latest on npm

Audit

Dependencies

uWebSockets.jsrequiredUnderlying WebSocket library; ultimate-ws wraps uWebSockets.js for high performance

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dimdenGD/ultimate-ws ↗

packageultimate-ws ↗

homepagehttps://github.com/dimdenGD/ultimate-ws#readme ↗