Registry / devops / websocket-express

websocket-express

library4.1.0jsnpmunverified

WebSocket-Express v4.1.0 extends Express with WebSocket support via the ws library, providing a unified API for HTTP and WebSocket handling. Unlike express-ws, it avoids monkey-patching Express objects, fully supports async/await, transactions for reliable message delivery, and TypeScript types out of the box. Requires peer dependencies express@5.x and ws@8.x. Released under MIT license, actively maintained.

devops

npm install websocket-express

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBSOCKET-EXPRESS

websocket-express

devopsjavascriptv4.1.0

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.

WebSocketExpress

✓ import { WebSocketExpress } from 'websocket-express'

✗ const WebSocketExpress = require('websocket-express')

ESM-only; exports are named, not default. CJS require will not work without interop.

Router

✓ import { Router } from 'websocket-express'

✗ import Router from 'websocket-express'

Named export, not default. Also supports ordinary express.Router but only websocket-express Router provides ws() method.

WebSocketRequest

✓ import type { WebSocketRequest } from 'websocket-express'

✗ import { WebSocketRequest } from 'websocket-express'

Type-only import. Use `import type` for TypeScript type in v4+ to avoid runtime inclusion.

Creates an Express+WebSocket server with a simple echo endpoint. Shows import, router.ws, accept, and listening.

import { WebSocketExpress, Router } from 'websocket-express'; const app = new WebSocketExpress(); const router = new Router(); router.ws('/echo', async (req, res) => { const ws = await res.accept(); ws.on('message', (msg) => ws.send(`echo: ${msg}`)); ws.send('connected'); }); app.use(router); const server = app.createServer(); server.listen(3000, () => console.log('Server on :3000'));

Debug

Known issues

breakingv4.0.0 drops Node 10/12 and uses Express 5 (with @types/express@5). Express 5 changed res.json() signature and removed some APIs.

fix

Upgrade to Express 5 and update any Express middleware to be compatible.

affects: >=4.0.0 <5.0.0

breakingv4.0.0 removed default export. Must use named imports: `import { WebSocketExpress } from 'websocket-express'` instead of `import WebSocketExpress from 'websocket-express'`.

fix

Switch to named imports.

affects: >=4.0.0

deprecated`res.reject()` is deprecated in v4.1.0. Use `res.abandon()` or call `next()` instead to pass the request to the next handler.

fix

Replace `res.reject()` with `res.abandon()` or `next()`.

affects: >=4.1.0

gotchaUsing `app.use(middleware)` will process WebSocket upgrade requests through the middleware. If middleware expects HTTP only, it may break. Use `app.useHTTP` for HTTP-only middleware.

fix

Use `app.useHTTP(middleware)` for non-WebSocket-aware middleware.

affects: *

gotcha`ws.nextMessage()` can hang indefinitely if no message is received. Always pass a timeout option to avoid resource leaks.

fix

Use `ws.nextMessage({ timeout: 5000 })` to set a timeout.

affects: *

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

Using CommonJS require() to import an ESM-only package.

fix

Change to `import { WebSocketExpress } from 'websocket-express'` or use dynamic import with `import('websocket-express')`.

TypeError: app.use is not a function

Instantiating WebSocketExpress incorrectly (e.g., calling `new` on an import that is the class itself).

fix

Ensure correct import: `import { WebSocketExpress } from 'websocket-express'` then `const app = new WebSocketExpress();`

TypeScript error: Module 'websocket-express' has no exported member 'Router'

Using an older version (<4.0.0) that exported differently, or incorrect import syntax.

fix

Upgrade to v4.1.x and use `import { Router } from 'websocket-express'`.

Cannot find module 'express' (or 'ws')

Peer dependencies not installed.

fix

Run `npm install express ws @types/express @types/ws`.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

expressrequiredPeer dependency, provides HTTP server and routing

wsrequiredPeer dependency, provides WebSocket implementation

@types/expressoptionalRequired for TypeScript projects

@types/wsoptionalRequired for TypeScript projects

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/davidje13/websocket-express ↗

packagewebsocket-express ↗

homepagehttps://github.com/davidje13/websocket-express#readme ↗