{"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,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","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"}