{"id":47537,"library":"express-ws","title":"express-ws","description":"Adds WebSocket endpoints to Express applications using the ws library. Version 5.0.2 (latest stable) is maintained with updates as needed. Express-ws enables defining WebSocket routes with standard Express middleware support, working seamlessly with Express routers. It modifies the global Router prototype by default and supports custom server instances and WebSocket options. The package requires Express peer dependency (express ^4.0.0 || ^5.0.0-alpha.1) and Node >=4.5.0. Key differentiator: minimal syntax compared to raw ws usage, but suffers from prototype monkey-patching and thread-unsafe design.","status":"active","version":"5.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/HenningM/express-ws","tags":["javascript","express","ws","websocket"],"install":[{"cmd":"npm install express-ws","lang":"bash","label":"npm"},{"cmd":"yarn add express-ws","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-ws","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Express is a peer dependency; the module adds .ws method to Express app and Router prototypes.","package":"express","optional":false},{"reason":"WebSocket library used under the hood for actual WebSocket server implementation.","package":"ws","optional":false}],"imports":[{"note":"express-ws is CJS-only. Use require or await import('express-ws') then call the default export.","wrong":"import expressWs from 'express-ws'; expressWs(app); // ESM import not supported; must use require or dynamic import","symbol":"default","correct":"const expressWs = require('express-ws')(app);"},{"note":"You must first initialize with the app, then call applyTo on the returned object.","wrong":"const { applyTo } = require('express-ws'); applyTo(router); // applyTo is not a named export; it's a method on the returned instance","symbol":"expressWs.applyTo","correct":"const expressWs = require('express-ws')(app); expressWs.applyTo(router);"},{"note":"getWss returns the underlying WebSocketServer instance. Access clients via wss.clients.","wrong":"const { getWss } = require('express-ws'); getWss(); // same issue: not a named export","symbol":"wsInstance.getWss","correct":"const expressWs = require('express-ws')(app); const wss = expressWs.getWss();"}],"quickstart":{"code":"const express = require('express');\nconst app = express();\nconst expressWs = require('express-ws')(app);\n\napp.ws('/echo', (ws, req) => {\n  ws.on('message', msg => {\n    ws.send(`echo: ${msg}`);\n  });\n});\n\napp.listen(3000, () => console.log('Server running on port 3000'));","lang":"javascript","description":"Creates an Express app, adds WebSocket support, and defines an echo WebSocket endpoint at /echo."},"warnings":[{"fix":"Use option `leaveRouterUntouched: true` and manually call `expressWs.applyTo(router)` on each router you want WebSocket support. Or consider using ws directly.","message":"express-ws modifies the global Router prototype. This affects all subsequent Router instances created with express.Router(), including those from other modules.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Initialize express-ws immediately after creating the app, before any router definitions or app.use calls.","message":"Calling `require('express-ws')(app)` after defining routes/routers will break. express-ws must be initialized before any routers that use .ws.","severity":"gotcha","affected_versions":"all"},{"fix":"Clone the set before iterating: const clients = [...wss.clients]; clients.forEach(...).","message":"The ws library's `clients` property is not safe for iteration in production; it is a Set but can change size during iteration. express-ws does not protect against this.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Initialize with wsOptions: { maxPayload: 100 * 1024 } for global settings, or handle per-connection in the callback.","message":"express-ws does not support passing options to the WebSocket server per route; the wsOptions in constructor apply globally. Cannot set maxPayload etc per endpoint.","severity":"gotcha","affected_versions":"all"},{"fix":"Use const expressWs = await import('express-ws'); expressWs.default(app); but note it's still CJS under the hood.","message":"The default export pattern (require('express-ws')(app)) is common but not tree-shakable and prevents static analysis.","severity":"deprecated","affected_versions":">=5.0.0"}],"env_vars":null,"search_vec":"'4.0.0':64 '4.5.0':69 '5.0.0':65 '5.0.2':15 'add':4 'alpha.1':66 'applic':9 'compar':74 'custom':51 'default':48 'defin':28 'depend':62 'design':90 'differenti':71 'enabl':27 'endpoint':6 'express':2,8,25,33,39,60,63,92 'express-w':1,24 'global':44 'instanc':53 'javascript':91 'key':70 'latest':16 'librari':13 'maintain':19 'middlewar':34 'minim':72 'modifi':42 'monkey':84 'monkey-patch':83 'need':23 'node':68 'option':56 'packag':58 'patch':85 'peer':61 'prototyp':46,82 'raw':76 'requir':59 'rout':30 'router':40,45 'seamless':37 'server':52 'stabl':17 'standard':32 'suffer':80 'support':35,50 'syntax':73 'thread':88 'thread-unsaf':87 'unsaf':89 'updat':21 'usag':78 'use':10 'version':14 'websocket':5,29,55,94 'work':36 'ws':3,12,26,77,93","created_at":"2026-06-07T16:52:01.332837+00:00","updated_at":"2026-06-07T16:52:01.332837+00:00","problems":[{"fix":"Ensure require('express-ws')(app) is called before any route definitions.","cause":"express-ws not initialized before calling app.ws.","error":"TypeError: app.ws is not a function"},{"fix":"Initialize express-ws first, or call expressWs.applyTo(router).","cause":"express-ws initialized after creating the router, or `leaveRouterUntouched: true` without calling applyTo.","error":"TypeError: router.ws is not a function"},{"fix":"Use require('express-ws') or dynamic import with await import('express-ws').","cause":"Trying to use ESM import syntax with express-ws (CJS only).","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"Configure the proxy to forward Upgrade headers, or use the 'server' option in expressWs to pass the raw http.Server.","cause":"Server is behind a proxy or load balancer that doesn't handle WebSocket upgrade.","error":"Upgrade required for websocket connection - handshake failed"}],"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/HenningM/express-ws","github":"https://github.com/HenningM/express-ws","docs":null,"changelog":null,"pypi":null,"npm":"express-ws","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"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}}