Registry / messaging / websocket-nats

websocket-nats

JSON →
library0.3.3jsnpmunverified

A browser-based WebSocket client for NATS messaging system, version 0.3.3. It enables in-browser connectivity to NATS servers via a WebSocket-to-TCP proxy. The library mirrors the node-nats API, supporting publish/subscribe, request/reply, wildcard subscriptions, queue groups, and clustered connections. Unlike server-side NATS clients, it operates entirely in the browser and requires an external WebSocket proxy. The project appears to be in maintenance mode with no recent updates since 2017.

messaging
npm install websocket-nats
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · WEBSOCKET-NATS
W
websocket-nats
messagingjavascriptv0.3.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.

connect
✓ var nats = require('websocket-nats').connect('ws://localhost:4223');
✗ import { connect } from 'websocket-nats';
The library uses CommonJS require() style and does not support ES module imports. It exports a function 'connect' as a property of the module.
nats
✓ var nc = require('websocket-nats').connect({'servers': servers});
✗ const nats = require('websocket-nats'); nats.connect('ws://...');
The connect function is the default export, accessible via require('websocket-nats').connect. The module itself is a function object with additional methods like 'publish', 'subscribe', etc. returned by connect.
websocket-nats bundle via CDN
✓ <script src='.../websocket-nats.min.js'></script> <!-- global `Nats` object -->
✗ Requiring via AMD or other module formats; the bundle sets window.Nats.
When using the CDN bundle, the library is exposed as the global 'Nats' object. You can then use Nats.connect() etc.
connect options
✓ var nc = require('websocket-nats').connect({'servers': ['ws://...'], 'dontRandomize': true});
✗ connect('ws://...', {'dontRandomize': true}) // incorrect: options must be first argument for clustered usage
When passing a servers array, the first argument must be an options object, not a URL string. For single server, pass URL string directly.
subscription callback signature
✓ nats.subscribe('foo', function(msg, reply, subject) { ... });
✗ nats.subscribe('foo', function(msg) { ... }); // missing reply and subject parameters
The callback receives (msg, reply?, subject). Many users forget reply and subject, especially when using patterns from other NATS clients.

Shows basic publish, subscribe, request/reply, and close with a WebSocket NATS client in a browser-like environment.

var nats = require('websocket-nats').connect('ws://localhost:4223'); // Simple Publisher nats.publish('foo', 'Hello World!'); // Simple Subscriber nats.subscribe('foo', function(msg) { console.log('Received a message: ' + msg); }); // Request with auto-unsubscribe nats.request('help', null, {'max':1}, function(response) { console.log('Got a response for help: ' + response); }); // Replies nats.subscribe('help', function(request, replyTo) { nats.publish(replyTo, 'I can help!'); }); // Close connection nats.close();
Debug
Known issues
breakingThis library does not support TLS natively. You must configure your WebSocket proxy to handle TLS.
fix
Use a WebSocket proxy like ws-tcp-relay with TLS termination, or use wss:// URLs with a proxy that handles SSL.
affects: all
gotchaThe library requires an external WebSocket-to-TCP proxy to connect to a NATS server. It does not connect directly to gnatsd.
fix
Set up and run a proxy such as ws-tcp-relay (https://github.com/isobit/ws-tcp-relay) before connecting.
affects: all
deprecatedPackage has not been updated since 2017. It uses outdated dependencies and is not compatible with modern tooling (ESM, TypeScript).
fix
Consider using the official NATS WebSocket client (nats.ws) from the NATS team, which is actively maintained and supports modern JS.
affects: all
gotchaThe library exposes a 'Nats' global when loaded via CDN, which may conflict with other libraries or the NATS namespace.
fix
Use the npm package via a bundler to avoid global scope pollution, or rename the global if necessary.
affects: all
gotchaThe 'connect' function returns a client object that is also callable? The module.exports is the connect function itself, which can lead to confusion if you try to call methods on the require result directly.
fix
Always use the object returned by connect() for subscriptions and publications, not the module itself.
affects: all
gotchaThe subscription callback signature includes 'reply' and 'subject' after 'msg'. Missing these parameters may cause undefined errors when using request/response.
fix
Always define at least (msg, reply, subject) in your subscription callbacks, even if you don't use them.
affects: all
Errors
Common errors & fixes
Error: connect ECONNREFUSED ws://localhost:4223
No WebSocket proxy is running on the specified host/port.
fix
Ensure your WebSocket-to-TCP proxy (e.g., ws-tcp-relay) is running and listening on port 4223, and that the NATS server gnatsd is accessible.
TypeError: nats.publish is not a function
Calling publish on the module itself instead of the client instance returned by connect().
fix
Assign the result of connect() to a variable: var nc = require('websocket-nats').connect(...); nc.publish(...);
WebSocket connection to 'ws://localhost:4223/' failed: Unexpected response code: 400
The requested WebSocket protocol or path is not accepted by the proxy.
fix
Check that the proxy is configured to accept WebSocket connections on that URL. Usually the path is just '/', but some proxies require a specific path like '/nats'.
Uncaught ReferenceError: require is not defined
Using CommonJS require() in an ES module or browser environment without a bundler.
fix
Use the CDN script tag to load the library (adds global 'Nats'), or bundle with Webpack/Browserify.
Cannot read property 'host' of undefined
Accessing nc.currentServer before connection is established or after connection fails.
fix
Check that connection succeeded by listening to the 'connect' event or checking nc.connected before accessing nc.currentServer.
Upgrade
Version history
0.3.3latest on npm
Audit
Dependencies
websocket-natsrequiredThe library itself is the dependency; no other notable peer or runtime dependencies beyond the browser's native WebSocket API.
Agent activity
21 hits · last 30 days
node
20
OpenAI (training)
1
Resources
githubhttps://github.com/isobit/websocket-nats ↗
packagewebsocket-nats ↗
homepagehttps://github.com/isobit/websocket-nats#readme ↗