{"id":49724,"library":"websocket-lib","title":"websocket-lib","description":"A lightweight WebSocket library for Node.js at version 3.3.0 (released 2023). It provides a simple API to create WebSocket servers and clients, with session-based event handling (data, close). The library supports both Node.js and browser environments. Key differentiators: minimal dependencies, straightforward stream-like API, and no external WebSocket library required (uses native 'net' and 'crypto' modules). Release cadence is sporadic, with the last update in 2023.","status":"active","version":"3.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/Lanfei/websocket-lib","tags":["javascript","websocket","ws","socket","stream","realtime"],"install":[{"cmd":"npm install websocket-lib","lang":"bash","label":"npm"},{"cmd":"yarn add websocket-lib","lang":"bash","label":"yarn"},{"cmd":"pnpm add websocket-lib","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v3, the library is ESM-only. Use named import for server creation.","wrong":"const createServer = require('websocket-lib').createServer","symbol":"createServer","correct":"import { createServer } from 'websocket-lib'"},{"note":"Named import 'connect' is preferred over default import.","wrong":"const ws = require('websocket-lib'); ws.connect(...)","symbol":"connect","correct":"import { connect } from 'websocket-lib'"},{"note":"The library exports both a default object and named exports. Default import gives access to both createServer and connect as methods.","wrong":"const ws = require('websocket-lib')","symbol":"default import","correct":"import ws from 'websocket-lib'"}],"quickstart":{"code":"import { createServer, connect } from 'websocket-lib';\n\n// Server\nconst server = createServer((session) => {\n  console.log('Client connected');\n  session.on('data', (data) => {\n    console.log('Received:', data);\n    session.send('Hello ' + data);\n  });\n  session.on('close', () => console.log('Session closed'));\n});\nserver.listen(8080, () => console.log('Server on :8080'));\n\n// Client\nconst client = connect('ws://localhost:8080', (session) => {\n  session.setEncoding('utf8');\n  session.send('Client');\n  session.on('data', (data) => console.log('Server:', data));\n});","lang":"typescript","description":"Creates a WebSocket server on port 8080, echos back messages with 'Hello ', and a client connects, sends 'Client', and logs the server response."},"warnings":[{"fix":"Use session callback in createServer() instead of server.on('connection', ...).","message":"EventEmitter removal: 'connection' event removed from server.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use ESM imports (import ... from 'websocket-lib') or use dynamic import() inside CJS.","message":"The library is ESM-only since v3. CommonJS require() will throw an error.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Add session.setEncoding('utf8') in the connection callback to receive strings.","message":"Session 'data' event emits raw Buffer; must call session.setEncoding('utf8') for string.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the global WebSocket class in browsers; do not import websocket-lib client-side.","message":"Browser usage requires native WebSocket; the library only works on Node.js.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2023':14,72 '3.3.0':12 'api':19,50 'base':29 'browser':40 'cadenc':64 'client':25 'close':33 'creat':21 'crypto':61 'data':32 'depend':45 'differenti':43 'environ':41 'event':30 'extern':53 'handl':31 'javascript':73 'key':42 'last':69 'lib':3 'librari':7,35,55 'lightweight':5 'like':49 'minim':44 'modul':62 'nativ':58 'net':59 'node.js':9,38 'provid':16 'realtim':78 'releas':13,63 'requir':56 'server':23 'session':28 'session-bas':27 'simpl':18 'socket':76 'sporad':66 'straightforward':46 'stream':48,77 'stream-lik':47 'support':36 'updat':70 'use':57 'version':11 'websocket':2,6,22,54,74 'websocket-lib':1 'ws':75","created_at":"2026-06-07T17:03:17.098082+00:00","updated_at":"2026-06-07T17:03:17.098082+00:00","problems":[{"fix":"Switch to ESM: import { createServer } from 'websocket-lib'","cause":"Using CommonJS require with v3 which is ESM-only.","error":"TypeError: require(...).createServer is not a function"},{"fix":"Use import() dynamic import or convert project to ESM.","cause":"Trying to require an ESM module in CommonJS.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /node_modules/websocket-lib/index.js from ... not supported."},{"fix":"Use createServer((session) => { session.send(...) })","cause":"Using event listener 'connection' instead of session callback.","error":"TypeError: session.send is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/Lanfei/websocket-lib#readme","github":"https://github.com/Lanfei/websocket-lib","docs":null,"changelog":null,"pypi":null,"npm":"websocket-lib","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}