{"id":49729,"library":"websocket-nats","title":"websocket-nats","description":"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.","status":"maintenance","version":"0.3.3","language":"javascript","source_language":"en","source_url":"https://github.com/isobit/websocket-nats","tags":["javascript","websocket","websockets","ws","nats","browser"],"install":[{"cmd":"npm install websocket-nats","lang":"bash","label":"npm"},{"cmd":"yarn add websocket-nats","lang":"bash","label":"yarn"},{"cmd":"pnpm add websocket-nats","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The library itself is the dependency; no other notable peer or runtime dependencies beyond the browser's native WebSocket API.","package":"websocket-nats","optional":false}],"imports":[{"note":"The library uses CommonJS require() style and does not support ES module imports. It exports a function 'connect' as a property of the module.","wrong":"import { connect } from 'websocket-nats';","symbol":"connect","correct":"var nats = require('websocket-nats').connect('ws://localhost:4223');"},{"note":"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.","wrong":"const nats = require('websocket-nats'); nats.connect('ws://...');","symbol":"nats","correct":"var nc = require('websocket-nats').connect({'servers': servers});"},{"note":"When using the CDN bundle, the library is exposed as the global 'Nats' object. You can then use Nats.connect() etc.","wrong":"Requiring via AMD or other module formats; the bundle sets window.Nats.","symbol":"websocket-nats bundle via CDN","correct":"<script src='.../websocket-nats.min.js'></script> <!-- global `Nats` object -->"},{"note":"When passing a servers array, the first argument must be an options object, not a URL string. For single server, pass URL string directly.","wrong":"connect('ws://...', {'dontRandomize': true}) // incorrect: options must be first argument for clustered usage","symbol":"connect options","correct":"var nc = require('websocket-nats').connect({'servers': ['ws://...'], 'dontRandomize': true});"},{"note":"The callback receives (msg, reply?, subject). Many users forget reply and subject, especially when using patterns from other NATS clients.","wrong":"nats.subscribe('foo', function(msg) { ... }); // missing reply and subject parameters","symbol":"subscription callback signature","correct":"nats.subscribe('foo', function(msg, reply, subject) { ... });"}],"quickstart":{"code":"var nats = require('websocket-nats').connect('ws://localhost:4223');\n\n// Simple Publisher\nnats.publish('foo', 'Hello World!');\n\n// Simple Subscriber\nnats.subscribe('foo', function(msg) {\n  console.log('Received a message: ' + msg);\n});\n\n// Request with auto-unsubscribe\nnats.request('help', null, {'max':1}, function(response) {\n  console.log('Got a response for help: ' + response);\n});\n\n// Replies\nnats.subscribe('help', function(request, replyTo) {\n  nats.publish(replyTo, 'I can help!');\n});\n\n// Close connection\nnats.close();","lang":"javascript","description":"Shows basic publish, subscribe, request/reply, and close with a WebSocket NATS client in a browser-like environment."},"warnings":[{"fix":"Use a WebSocket proxy like ws-tcp-relay with TLS termination, or use wss:// URLs with a proxy that handles SSL.","message":"This library does not support TLS natively. You must configure your WebSocket proxy to handle TLS.","severity":"breaking","affected_versions":"all"},{"fix":"Set up and run a proxy such as ws-tcp-relay (https://github.com/isobit/ws-tcp-relay) before connecting.","message":"The library requires an external WebSocket-to-TCP proxy to connect to a NATS server. It does not connect directly to gnatsd.","severity":"gotcha","affected_versions":"all"},{"fix":"Consider using the official NATS WebSocket client (nats.ws) from the NATS team, which is actively maintained and supports modern JS.","message":"Package has not been updated since 2017. It uses outdated dependencies and is not compatible with modern tooling (ESM, TypeScript).","severity":"deprecated","affected_versions":"all"},{"fix":"Use the npm package via a bundler to avoid global scope pollution, or rename the global if necessary.","message":"The library exposes a 'Nats' global when loaded via CDN, which may conflict with other libraries or the NATS namespace.","severity":"gotcha","affected_versions":"all"},{"fix":"Always use the object returned by connect() for subscriptions and publications, not the module itself.","message":"The '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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always define at least (msg, reply, subject) in your subscription callbacks, even if you don't use them.","message":"The subscription callback signature includes 'reply' and 'subject' after 'msg'. Missing these parameters may cause undefined errors when using request/response.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.3.3':15 '2017':81 'api':39 'appear':70 'base':7 'browser':6,20,61,87 'browser-bas':5 'client':9,55 'cluster':48 'connect':21,49 'enabl':17 'entir':58 'extern':65 'group':46 'in-brows':18 'javascript':82 'librari':33 'mainten':74 'messag':12 'mirror':34 'mode':75 'nat':3,11,23,38,54,86 'node':37 'node-nat':36 'oper':57 'project':69 'proxi':31,67 'publish/subscribe':41 'queue':45 'recent':78 'request/reply':42 'requir':63 'server':24,52 'server-sid':51 'side':53 'sinc':80 'subscript':44 'support':40 'system':13 'tcp':30 'unlik':50 'updat':79 'version':14 'via':25 'websocket':2,8,28,66,83,84 'websocket-nat':1 'websocket-to-tcp':27 'wildcard':43 'ws':85","created_at":"2026-06-07T17:03:18.639889+00:00","updated_at":"2026-06-07T17:03:18.639889+00:00","problems":[{"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.","cause":"No WebSocket proxy is running on the specified host/port.","error":"Error: connect ECONNREFUSED ws://localhost:4223"},{"fix":"Assign the result of connect() to a variable: var nc = require('websocket-nats').connect(...); nc.publish(...);","cause":"Calling publish on the module itself instead of the client instance returned by connect().","error":"TypeError: nats.publish is not a function"},{"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'.","cause":"The requested WebSocket protocol or path is not accepted by the proxy.","error":"WebSocket connection to 'ws://localhost:4223/' failed: Unexpected response code: 400"},{"fix":"Use the CDN script tag to load the library (adds global 'Nats'), or bundle with Webpack/Browserify.","cause":"Using CommonJS require() in an ES module or browser environment without a bundler.","error":"Uncaught ReferenceError: require is not defined"},{"fix":"Check that connection succeeded by listening to the 'connect' event or checking nc.connected before accessing nc.currentServer.","cause":"Accessing nc.currentServer before connection is established or after connection fails.","error":"Cannot read property 'host' of undefined"}],"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/isobit/websocket-nats#readme","github":"https://github.com/isobit/websocket-nats","docs":null,"changelog":null,"pypi":null,"npm":"websocket-nats","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}}