wse

library4.12.3jsnpmunverified

Wse (WebSocket Everywhere!) is a lightweight WebSocket wrapper for Node.js (v14+) and browsers that adds authentication, RPC support, multi-device messaging, and custom protocol handling. Current stable version is 4.12.3, released periodically. It integrates seamlessly with Fastify, Express, or plain HTTP servers without requiring a dedicated WebSocket port. Key differentiators: built-in RPC-like API without brokers or routers, simple auth via the 'identify' callback, and channel-based broadcasting for multi-device scenarios.

messaging

npm install wse

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WSE

wse

messagingjavascriptv4.12.3

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.

WseServer

✓ import { WseServer } from 'wse'

✗ const WseServer = require('wse')

Package is ESM-only. CommonJS require will fail.

WseClient

✓ import { WseClient } from 'wse'

✗ const WseClient = require('wse')

ESM-only; named export.

default

✓ import wse from 'wse'

Default export is the entire module; prefer named imports for tree-shaking.

WseServer

✓ import { WseServer } from 'wse'

✗ import { Server } from 'wse'

The class is named WseServer, not Server.

WseClient

✓ import { WseClient } from 'wse'

✗ import { Client } from 'wse'

The class is named WseClient, not Client.

Creates a WseServer on port 4200 with simple auth, listens for 'chat' messages, registers a 'ping' RPC, and connects a WseClient to send messages and call RPC.

import { WseServer, WseClient } from 'wse' // Server const server = new WseServer({ port: 4200, identify: ({ accept }) => accept('user-' + Date.now()) }) server.channel.on('chat', (conn, message) => { server.broadcast('chat', { user: conn.cid, message }) }) server.register('ping', () => 'pong') // Client (run in separate process or after server is ready) const client = new WseClient({ url: 'ws://localhost:4200' }) await client.connect() client.send('chat', 'Hello world!') const result = await client.call('ping') console.log(result) // 'pong' // Clean up client.disconnect() server.close()

Debug

Known issues

gotchaThe 'identify' callback must call accept() or reject() explicitly; omitting the call will leave the connection hanging.

fix

Always call accept('user-id') or reject(new Error('auth failed')) inside the identify callback.

affects: >=4.0.0

gotchaBroadcasting via server.broadcast only works if the channel option is set; otherwise it's a no-op.

fix

Set the 'channel' option on the server (or use the default channel) to enable broadcast.

affects: >=4.0.0

gotchaThe client.connect() must be awaited. Forgetting await leads to race conditions.

fix

Always use await client.connect() before sending or calling.

affects: >=4.0.0

gotchaWhen using with Express/Fastify, the server must be created with an http server instance; passing only port may cause conflicts.

fix

Pass an existing HTTP server to the WseServer constructor: new WseServer({ server: httpServer, identify: ... })

affects: >=4.0.0

deprecatedUsage of 'require' is deprecated; package is ESM-only.

fix

Use import statements or set "type": "module" in package.json.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: wse.WseServer is not a constructor

Using CommonJS require instead of ESM import.

fix

Replace const { WseServer } = require('wse') with import { WseServer } from 'wse'

Error: WebSocket connection to 'ws://localhost:4200' failed: Connection closed before receiving a handshake response

Server's identify callback threw an error or called reject() without proper error handling.

fix

Ensure identify calls accept() or reject() correctly and the client URL is correct.

TypeError: Cannot read properties of undefined (reading 'on')

Accessing server.channel before the channel is initialized (e.g., when channel option is not set).

fix

Set the 'channel' option on the server: new WseServer({ channel: 'myapp', ... })

Upgrade

Version history

4.12.3latest on npm

Audit

Dependencies

wsrequiredWebSocket implementation used by the server; the client uses native WebSocket in browser or ws in Node

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vovchisko/wse ↗

packagewse ↗

homepagehttps://github.com/vovchisko/wse#readme ↗