{"id":16583,"library":"webstomp-client","title":"Webstomp Client","description":"webstomp-client is a JavaScript library providing a STOMP client over WebSockets for both browser and Node.js environments. Currently at version 1.2.6, it does not follow a fixed release cadence but rather ships updates as needed, addressing bug fixes and minor enhancements. This project is an active fork of the original `stomp-websocket` library by Jeff Mesnil and Jeff Lindsay, having been rewritten in ES6 to modernize its codebase and integrate community-contributed pull requests that were pending in the upstream project. Its key differentiators include modern ES6 syntax, built-in TypeScript type definitions, and explicit support for supplying custom WebSocket implementations (e.g., `ws` or `sockjs-client` in Node.js) via the `webstomp.over()` method, rather than relying solely on a global `WebSocket` object like its predecessor or browser-only alternatives. For browser environments, it automatically uses the global `WebSocket` object. It provides a robust API for connecting, subscribing, sending messages, and handling disconnections with STOMP servers like RabbitMQ Web-STOMP.","status":"active","version":"1.2.6","language":"javascript","source_language":"en","source_url":"https://github.com/JSteunou/webstomp-client","tags":["javascript","stomp","webstomp","websocket","typescript"],"install":[{"cmd":"npm install webstomp-client","lang":"bash","label":"npm"},{"cmd":"yarn add webstomp-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add webstomp-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v1.2.3, the package exclusively uses a default export. Named imports for the main 'webstomp' object will fail.","wrong":"import { webstomp } from 'webstomp-client';","symbol":"webstomp","correct":"import webstomp from 'webstomp-client';"},{"note":"Type import for the STOMP Client instance.","symbol":"Client (type)","correct":"import type { Client } from 'webstomp-client';"},{"note":"Type import for STOMP frame objects returned in callbacks.","symbol":"Frame (type)","correct":"import type { Frame } from 'webstomp-client';"},{"note":"Standard CommonJS import pattern. The `webstomp` object will contain `client`, `over`, etc.","symbol":"webstomp (CommonJS)","correct":"const webstomp = require('webstomp-client');"}],"quickstart":{"code":"import webstomp from 'webstomp-client';\nimport WebSocket from 'ws'; // For Node.js, install 'ws': npm install ws\n\nconst WEBSOCKET_URL = process.env.STOMP_WS_URL ?? 'ws://localhost:15674/ws'; // Example: RabbitMQ Web-STOMP\nconst STOMP_USER = process.env.STOMP_USER ?? 'guest';\nconst STOMP_PASS = process.env.STOMP_PASS ?? 'guest';\n\nasync function runStompClient() {\n  console.log(`Attempting to connect to STOMP WebSocket at: ${WEBSOCKET_URL}`);\n\n  // In Node.js, a WebSocket implementation must be explicitly provided to webstomp.over()\n  // The protocols array ensures the WebSocket connection is established with STOMP-compatible subprotocols.\n  const ws = new WebSocket(WEBSOCKET_URL, ['v10.stomp', 'v11.stomp', 'v12.stomp']);\n\n  const client = webstomp.over(ws, {\n    debug: true,\n    heartbeat: { incoming: 10000, outgoing: 10000 } // Configure heartbeats\n  });\n\n  client.connect(\n    { login: STOMP_USER, passcode: STOMP_PASS },\n    (frame: webstomp.Frame) => {\n      console.log('Successfully connected to STOMP server:', frame.headers['session']);\n\n      client.subscribe('/queue/example', (message: webstomp.Frame) => {\n        console.log('Received message:', message.body);\n      }, { id: 'my-subscription' }); // Include a unique ID for the subscription\n\n      console.log('Subscribed to /queue/example');\n\n      setTimeout(() => {\n        const messageBody = `Hello from webstomp-client at ${new Date().toISOString()}`;\n        client.send('/queue/example', messageBody, { 'content-type': 'text/plain' });\n        console.log('Sent message:', messageBody);\n      }, 2000);\n\n      setTimeout(() => {\n        client.disconnect(() => {\n          console.log('Disconnected from STOMP server.');\n          ws.close();\n        });\n      }, 5000);\n    },\n    (error: webstomp.Frame | CloseEvent) => {\n      console.error('STOMP connection error:', error);\n      if (error instanceof CloseEvent) {\n          console.error(`WebSocket closed with code ${error.code} and reason: ${error.reason}`);\n      }\n      ws.close();\n    }\n  );\n\n  ws.onopen = () => console.log('WebSocket connection opened.');\n  ws.onclose = () => console.log('WebSocket connection closed.');\n  ws.onerror = (err: Event) => console.error('WebSocket error:', err);\n}\n\nrunStompClient().catch(console.error);","lang":"typescript","description":"Demonstrates connecting to a STOMP server via WebSockets in a Node.js environment using `webstomp.over()`, subscribing to a queue, sending a message, and properly disconnecting. Requires a running STOMP server (e.g., RabbitMQ with Web-STOMP plugin) and the `ws` npm package for Node.js WebSocket support."},"warnings":[{"fix":"Change your imports to `import webstomp from 'webstomp-client';` and access methods as `webstomp.client()` or `webstomp.over()`.","message":"Version 1.2.3 removed mixed (named and default) exports. The library now exclusively uses a default export. If you were using named imports like `import { client, over } from 'webstomp-client';`, these will break.","severity":"breaking","affected_versions":">=1.2.3"},{"fix":"Install a WebSocket client (`npm install ws`) and use `webstomp.over(new WebSocket(url))` instead of `webstomp.client(url)`.","message":"In Node.js environments, `webstomp-client` does not provide a default WebSocket implementation. You must explicitly provide a WebSocket-alike object instance (e.g., from the `ws` or `sockjs-client` packages) to the `webstomp.over()` method.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the API documentation for the correct `connect` signature matching your authentication method. Example: `client.connect({ login, passcode }, connectCallback)` or `client.connect(headers, connectCallback)`.","message":"The `connect` method has multiple overloads for parameters (headers vs. login/passcode). Ensure you pass parameters correctly to avoid connection issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass `{ heartbeat: false }` in the options object during client initialization: `webstomp.over(ws, { heartbeat: false })`.","message":"When connecting to SockJS-based STOMP servers, it's often recommended to disable heartbeats by setting `heartbeat: false` in the options object passed to `client()` or `over()`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.2.6':25 'activ':50 'address':40 'altern':137 'api':152 'automat':142 'browser':18,135,139 'browser-on':134 'bug':41 'built':96 'built-in':95 'cadenc':33 'client':2,5,13,114 'codebas':73 'communiti':77 'community-contribut':76 'connect':154 'contribut':78 'current':22 'custom':106 'definit':100 'differenti':90 'disconnect':160 'e.g':109 'enhanc':45 'environ':21,140 'es6':69,93 'explicit':102 'fix':31,42 'follow':29 'fork':51 'global':127,145 'handl':159 'implement':108 'includ':91 'integr':75 'javascript':8,169 'jeff':60,63 'key':89 'librari':9,58 'like':130,164 'lindsay':64 'mesnil':61 'messag':157 'method':120 'minor':44 'modern':71,92 'need':39 'node.js':20,116 'object':129,147 'origin':54 'pend':83 'predecessor':132 'project':47,87 'provid':10,149 'pull':79 'rabbitmq':165 'rather':35,121 'releas':32 'reli':123 'request':80 'rewritten':67 'robust':151 'send':156 'server':163 'ship':36 'sockj':113 'sockjs-client':112 'sole':124 'stomp':12,56,162,168,170 'stomp-websocket':55 'subscrib':155 'suppli':105 'support':103 'syntax':94 'type':99 'typescript':98,173 'updat':37 'upstream':86 'use':143 'version':24 'via':117 'web':167 'web-stomp':166 'websocket':15,57,107,128,146,172 'webstomp':1,4,171 'webstomp-cli':3 'webstomp.over':119 'ws':110","created_at":"2026-04-22T04:51:08.762420+00:00","updated_at":"2026-04-22T04:51:08.762420+00:00","problems":[{"fix":"For Node.js, use `webstomp.over(new WebSocket(url))` with a custom WebSocket implementation like `ws`. Ensure you are using the default import: `import webstomp from 'webstomp-client';`.","cause":"Attempting to use `webstomp.client()` in Node.js where `WebSocket` is not globally available, or trying to use `client` as a named import after v1.2.3.","error":"TypeError: webstomp.client is not a function"},{"fix":"In Node.js, explicitly use `webstomp.over(ws_instance)` and pass an instance of a Node.js WebSocket client (e.g., from the `ws` package). Alternatively, you could polyfill `global.WebSocket = require('ws');` but `webstomp.over` is the idiomatic way.","cause":"Using `webstomp.client(url)` in a Node.js environment without globally polyfilling the `WebSocket` object.","error":"ReferenceError: WebSocket is not defined"},{"fix":"Use a type-only import: `import type { Client } from 'webstomp-client';`.","cause":"Trying to import the `Client` type (or `Frame` type) as a value import.","error":"TS2305: Module '\"webstomp-client\"' has no exported member 'Client'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/JSteunou/webstomp-client","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/webstomp-client","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-21","install_tag":null}}