crossws

library0.4.5jsnpmunverified

Cross-platform WebSocket server toolkit supporting Node.js, Deno, Bun, and Cloudflare Workers. Version 0.4.5 provides a unified hooks API with typed events, prebundled ws for Node.js with optional uWebSockets adapter, and tree-shakable ESM exports. It is maintained by the h3js organization and follows a regular release cadence. Key differentiators: zero per-connection callback overhead, conditional exports for each platform, and TypeScript-first developer experience.

messaging

npm install crossws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CROSSWS

crossws

messagingjavascriptv0.4.5

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.

defineWebSocketAdapter

✓ import { defineWebSocketAdapter } from 'crossws'

✗ const defineWebSocketAdapter = require('crossws')

ESM-only; no CommonJS export

createWebSocket

✓ import { createWebSocket } from 'crossws'

✗ import { createWS } from 'crossws'

Named export, not default; creates a WebSocket server from platform adapter

CrossWSAdapter

✓ import type { CrossWSAdapter } from 'crossws'

✗ import { CrossWSAdapter } from 'crossws'

Type only; not a runtime value

Creates a WebSocket echo server using crossws with typed adapter hooks and listens on port 3000.

import { defineWebSocketAdapter, createWebSocket } from 'crossws' const adapter = defineWebSocketAdapter({ async upgrade(req) { // Accept all connections return true }, async open(peer) { console.log('Client connected') }, async message(peer, message) { peer.send(message.text()) }, async close(peer) { console.log('Client disconnected') }, }) const ws = createWebSocket(adapter, { port: 3000 }) ws.listen() console.log('Listening on port 3000')

Debug

Known issues

gotchaESM-only package: crossws provides only ESM exports and does not support require() or CommonJS. Using require() will fail.

fix

Use import statements and ensure your project is configured for ESM (e.g., type: 'module' in package.json).

affects: >=0.4.0

deprecatedThe 'peer' argument in hooks is an instance of CrossWSPeer; direct property access like 'peer.connection' is deprecated. Use getters defined on the peer class.

fix

Access peer properties via methods (e.g., peer.url, peer.headers) instead of the underlying raw connection.

affects: >=0.4.0

gotchaSending binary data: peer.send() accepts string or Buffer (Node.js), Uint8Array (browsers/workers). On Bun and Workers, you must convert to the appropriate type.

fix

Use new TextEncoder().encode(msg) for string-to-binary conversion; avoid plain ArrayBuffer.

affects: >=0.3.0

gotchaPeer send() returns a promise that may reject silently; unhandled rejections can cause crashes.

fix

Always await or catch send() errors, e.g., peer.send(data).catch(console.error).

affects: >=0.3.0

gotchaCloudflare Workers: crossws relies on WebSocketPair; ensure compatibility with wrangler and proper response handling.

fix

Explicitly return a Response from the worker's fetch handler after upgrading.

affects: >=0.3.0

breakingIn v0.3.0, the API was rewritten: hooks changed from 'connection' to 'open' callback; the 'peer' object changed shape.

fix

Upgrade hooks: replace 'connection' with 'open' and update peer usage per documentation.

affects: >=0.3.0 <0.4.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/crossws/dist/index.mjs not supported.

crossws is ESM-only but project uses CommonJS require()

fix

Switch to ESM by adding type: 'module' to package.json or use dynamic import().

TypeError: peer.send is not a function

Using crossws with an incompatible adapter or incorrect peer reference (e.g., raw WebSocket instead of CrossWSPeer)

fix

Ensure you are using the peer object provided in hook callbacks, not the original raw WebSocket.

ReferenceError: defineWebSocketAdapter is not defined

Attempting to use crossws without importing defineWebSocketAdapter correctly

fix

Use the named import: import { defineWebSocketAdapter } from 'crossws'.

UnhandledPromiseRejectionWarning: Error: Connection closed before sending a message

Sending on an already closed WebSocket without checking readyState

fix

Check peer.readyState === 1 before sending, or catch send() rejections.

Upgrade

Version history

0.4.5latest on npm

Audit

Dependencies

srvxoptionalPeer dependency for server integration in cross-platform adapters

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/h3js/crossws ↗

packagecrossws ↗

homepagehttps://crossws.h3.dev ↗