{"id":10879,"library":"faye-websocket","title":"Faye-WebSocket","description":"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.","status":"abandoned","version":"0.11.4","language":"javascript","source_language":"en","source_url":"git://github.com/faye/faye-websocket-node","tags":["javascript","websocket","eventsource"],"install":[{"cmd":"npm install faye-websocket","lang":"bash","label":"npm"},{"cmd":"yarn add faye-websocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add faye-websocket","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core protocol parsing and framing for WebSocket connections.","package":"websocket-driver","optional":false}],"imports":[{"note":"The library is primarily CommonJS. Direct ESM named imports are not officially supported and may lead to errors (see GitHub issue #82).","wrong":"import WebSocket from 'faye-websocket';","symbol":"WebSocket","correct":"const WebSocket = require('faye-websocket');"},{"note":"The Client constructor is a static property of the main WebSocket export. ESM imports for this pattern are problematic.","wrong":"import { Client } from 'faye-websocket';","symbol":"WebSocket.Client","correct":"const WebSocket = require('faye-websocket');\nconst client = new WebSocket.Client('ws://example.com');"},{"note":"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.","wrong":"import { isWebSocket } from 'faye-websocket';","symbol":"WebSocket.isWebSocket","correct":"const WebSocket = require('faye-websocket');\nif (WebSocket.isWebSocket(request)) { /* ... */ }"}],"quickstart":{"code":"const WebSocket = require('faye-websocket');\nconst http = require('http');\n\n// --- WebSocket Server --- \nconst server = http.createServer();\n\nserver.on('upgrade', function(request, socket, body) {\n  if (WebSocket.isWebSocket(request)) {\n    const ws = new WebSocket(request, socket, body);\n\n    ws.on('message', function(event) {\n      console.log('Server received:', event.data);\n      ws.send(`Echo: ${event.data}`);\n    });\n\n    ws.on('close', function(event) {\n      console.log('Server closed:', event.code, event.reason);\n      ws = null;\n    });\n\n    ws.on('error', function(event) {\n      console.error('Server error:', event.message);\n    });\n  }\n});\n\nserver.listen(8000, () => {\n  console.log('WebSocket server listening on port 8000');\n});\n\n// --- WebSocket Client (connects to the server above) --- \nconst clientWs = new WebSocket.Client('ws://localhost:8000/');\n\nclientWs.on('open', function(event) {\n  console.log('Client connected');\n  clientWs.send('Hello from client!');\n});\n\nclientWs.on('message', function(event) {\n  console.log('Client received:', event.data);\n  if (event.data.includes('Echo')) {\n    clientWs.close(1000, 'Finished');\n  }\n});\n\nclientWs.on('close', function(event) {\n  console.log('Client closed:', event.code, event.reason);\n});\n\nclientWs.on('error', function(event) {\n  console.error('Client error:', event.message);\n});","lang":"javascript","description":"This example demonstrates both a basic Faye-WebSocket server that echoes messages and a client that connects to it, sends a message, and closes."},"warnings":[{"fix":"Review Apache 2.0 license terms for compatibility with your project's licensing and obligations.","message":"The 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.","severity":"breaking","affected_versions":">=0.11.3"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.11.0"},{"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.","message":"Detecting 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=0.11.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use CommonJS `require` syntax: `const WebSocket = require('faye-websocket');`. The library does not provide native ESM exports.","cause":"Attempting to use ES module `import { WebSocket } from 'faye-websocket';` syntax in an ESM context.","error":"Not able to load the library in ESM context using named import."},{"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.","cause":"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.","error":"Error during WebSocket handshake: 'Connection' header value is not 'Upgrade'"},{"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(...);`.","cause":"Incorrectly importing the `Client` constructor, often trying a named import for a submodule that is actually a property of the main export.","error":"TypeError: WebSocket.Client is not a constructor (or similar when trying to instantiate client)"}],"ecosystem":"npm"}