Registry / http-networking / faye-websocket

faye-websocket

JSON →
library0.11.4jsnpmunverified

Faye-WebSocket is a standards-compliant WebSocket server and client library designed for Node.js environments. Extracted from the larger Faye project, it provides a low-level, event-driven API for handling WebSocket connections (RFC 6455) and EventSource streams. Unlike a full WebSocket server, it integrates with existing Node.js HTTP servers by listening for 'upgrade' events. The latest stable version, 0.11.4, was published in May 2021. The project appears to be largely unmaintained and is considered inactive, with no new versions or significant development in the past five years. Its primary differentiation lies in providing a direct implementation of the WebSocket API without significant higher-level abstractions, allowing developers fine-grained control over the protocol.

http-networkingweb-framework
npm install faye-websocket
github ↗package ↗
INSTALL
IMPORT
SIG · FAYE-WEBSOCKET
F
faye-websocket
http-networkingjavascriptv0.11.4
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

WebSocket
✓ const WebSocket = require('faye-websocket');
✗ import WebSocket from 'faye-websocket';
The library is primarily CommonJS. Direct ESM named imports are not officially supported and may lead to errors (see GitHub issue #82).
WebSocket.Client
✓ const WebSocket = require('faye-websocket'); const client = new WebSocket.Client('ws://example.com');
✗ import { Client } from 'faye-websocket';
The Client constructor is a static property of the main WebSocket export. ESM imports for this pattern are problematic.
WebSocket.isWebSocket
✓ const WebSocket = require('faye-websocket'); if (WebSocket.isWebSocket(request)) { /* ... */ }
✗ import { isWebSocket } from 'faye-websocket';
Used on the server side to determine if an incoming HTTP 'upgrade' request is a WebSocket handshake. It's a static method on the main export.

This example demonstrates both a basic Faye-WebSocket server that echoes messages and a client that connects to it, sends a message, and closes.

const WebSocket = require('faye-websocket'); const http = require('http'); // --- WebSocket Server --- const server = http.createServer(); server.on('upgrade', function(request, socket, body) { if (WebSocket.isWebSocket(request)) { const ws = new WebSocket(request, socket, body); ws.on('message', function(event) { console.log('Server received:', event.data); ws.send(`Echo: ${event.data}`); }); ws.on('close', function(event) { console.log('Server closed:', event.code, event.reason); ws = null; }); ws.on('error', function(event) { console.error('Server error:', event.message); }); } }); server.listen(8000, () => { console.log('WebSocket server listening on port 8000'); }); // --- WebSocket Client (connects to the server above) --- const clientWs = new WebSocket.Client('ws://localhost:8000/'); clientWs.on('open', function(event) { console.log('Client connected'); clientWs.send('Hello from client!'); }); clientWs.on('message', function(event) { console.log('Client received:', event.data); if (event.data.includes('Echo')) { clientWs.close(1000, 'Finished'); } }); clientWs.on('close', function(event) { console.log('Client closed:', event.code, event.reason); }); clientWs.on('error', function(event) { console.error('Client error:', event.message); });
Debug
Known issues
breakingThe license for `faye-websocket` changed from MIT to Apache 2.0 in version 0.11.3. Users should be aware of the different licensing terms, particularly if integrating into projects with specific license requirements.
fix
Review Apache 2.0 license terms for compatibility with your project's licensing and obligations.
affects: >=0.11.3
gotchaWhen using `wss://` (secure WebSockets), `faye-websocket` client (since 0.11.0) performs server certificate verification by default. This can cause connection failures if the server certificate is invalid, self-signed, or not trusted by the client's system root certificates.
fix
Ensure the WebSocket server presents a valid, trusted SSL/TLS certificate. For development or specific scenarios, you can optionally disable certificate verification via the `tls` option in `WebSocket.Client` constructor, though this is not recommended for production.
affects: >=0.11.0
gotchaDetecting client-side dropped WebSocket connections can be unreliable. Browsers might not immediately trigger `onclose` events, leading to a 'half-open' connection state where the server perceives the client as active.
fix
Implement application-level heartbeats (ping/pong) to actively monitor connection liveness. The `ws.ping()` method can be used on the server, and the client should respond with a pong. Alternatively, set a `ping` option during server-side WebSocket construction.
affects: >=0.1.0
breakingThe library is essentially unmaintained since its last release in May 2021. It does not support native ESM imports directly, which may cause compatibility issues in modern Node.js projects that primarily use `import`/`export` syntax.
fix
Consider migrating to an actively maintained WebSocket library that provides native ESM support, such as `ws`. If continuing to use `faye-websocket`, explicitly use CommonJS `require()` statements.
affects: >=0.11.4
Errors
Common errors & fixes
Not able to load the library in ESM context using named import.
Attempting to use ES module `import { WebSocket } from 'faye-websocket';` syntax in an ESM context.
fix
Use CommonJS `require` syntax: `const WebSocket = require('faye-websocket');`. The library does not provide native ESM exports.
Error during WebSocket handshake: 'Connection' header value is not 'Upgrade'
The HTTP server or an intermediary proxy (like Nginx or Apache) is not correctly forwarding the 'Upgrade' header, or the server itself isn't set up to handle WebSocket upgrade requests.
fix
Ensure your HTTP server is configured to listen for and handle the `upgrade` event (e.g., `http.createServer().on('upgrade', ...)` in Node.js). If using a proxy, verify that it's configured to correctly proxy WebSocket upgrade requests, including the `Connection: Upgrade` and `Upgrade: websocket` headers.
TypeError: WebSocket.Client is not a constructor (or similar when trying to instantiate client)
Incorrectly importing the `Client` constructor, often trying a named import for a submodule that is actually a property of the main export.
fix
The `Client` class is a static property of the main `WebSocket` object. Import the main `WebSocket` object first, then access `WebSocket.Client`: `const WebSocket = require('faye-websocket'); const client = new WebSocket.Client(...);`.
Upgrade
Version history
0.11.4latest on npm
Audit
Dependencies
websocket-driverrequiredCore protocol parsing and framing for WebSocket connections.
Agent activity
52 hits · last 30 days
node
46
Bingbot
5
Resources
githubhttps://github.com/faye/faye-websocket-node ↗
packagehttps://www.npmjs.com/package/faye-websocket ↗