STOMP library for JavaScript/TypeScript.

7 minute read

Under heavy construction

General

Q: What are STOMP and WebStomp?

STOMP is a simple text protocol to interact with messaging brokers. Usually, one of AMQP, MQTT, JMS, or a similar protocol is used to connect to a messaging broker. In a language like JavaScript, it may not be easy to implement any of these protocols. So, STOMP becomes a reasonable option.

In addition, web browsers do not allow TCP connections from web pages. To overcome this limitation, most of the brokers support STOMP over WebSockets. The STOMP over WebSockets is referred to as WebStomp.

Q: What documentation is available?

Q: Which one should I use - stompjs or rx-stomp?

stompjs is the underlying core library, usable almost everywhere.

rx-stomp exposes functionality as RxJS primitives. If you are already using RxJS in your project or are familiar with it, please consider using rx-stomp.

Other than syntactical differences, these two variants have a very important difference. In stompjs, the client must only be used within the onConnect callback. Using it outside may produce strange errors. The rx-stomp does not suffer from this limitation.

So, as a rule of thumb, if your application needs to use the client object outside the onConnect callback, use rx-stomp.

When using with Angular, rx-stomp seems natual as Angular relies heavily on RxJS.

Q: Can these libraries be used with ES6 or Typescript?

Yes.

From 2023, these libraries are distributed as Javascript modules as default. These can be used with import.

All these libraries have been developed in TypeScript and type definition files are included in releases.

In addition, a UMD bundle is included to be used as a html script tag.

Q: I am using Angular. Which of stompjs or rx-stomp should I use?

Angular makes heavy use of RxJS. So using rx-stomp should feel natural with Angular.

There is a tutorial for using rx-stomp with Angular. Please see guides.

Having said all of these, you can use any of the variants. Developers have reported successfully using stompjs directly with Angular.

Q: Can I use libraries with bundlers like Rollup or Webpack?

Yes.

These libraries include ES6 modules in the distribution, so, any environment that uses import will be able to find modules without any additional configuration.

Q: Do these libraries work well with tree shaking?

Yes.

Please update the latest versions before reporting any issues related to tree shaking.

Q: What are Heartbeats? Should I bother?

Most STOMP 1.1+ brokers will support heart beats. These can be from the broker to the client (incoming) or the client to the broker (outgoing). When enabled, periodic heartbeats are sent. If heartbeats are not received within specified time (along with some grace time), the connection is assumed to be stale and will be terminated.

SockJS may not support heart beats. See using STOMP with SockJS.

Whether you should use heart beats is a complex decision. If you use it, a stale connection will be detected sooner. However, it also means packets (actually a one-byte payload) will keep getting sent/received even when there is no application traffic.

Please see the Heart Beats topic for usage details.

Q: How do I enable logging?

Please see enabling debug log.

The console debug output may have NULL characters, which will prevent it from copying and pasting into a GitHub issue. In such cases, save it as a text file and attach with the issue.

Q: Help me, I am getting errors about missing classes - TextEncoder/TextDecoder/WebSocket

Please see StompJs v5: Polyfills

SockJS

Q: Is SockJS needed to use these libraries?

No SockJS is not mandatory to use this library.

SockJS, however, is supported. Please see using StompJS with SockJS.

Q: I am using SockJS, my automatic reconnection does not work?

You need to pass a factory that returns a SockJS instance.

Please see Using STOMP with SockJS if you are using recent versions of these libraries.

If you are using Stomp.over compatibility mode (or older version), please refer to Stomp.over API docs.

Q: I am using SockJS and I am facing issues, where do I look?

Several topics related to SockJS have been compiled at Using STOMP with SockJS.

Authentication

Q: Can I use Token-based authentication with these libraries?

Even though WebSocket is somewhat similar to HTTP(S), it differs in one very important aspect — it does not allow control of headers.

This poses a limitation on using token-based authentication schemes using HTTP headers.

Conventional brokers do not expect any authentication information as part of HTTP headers or HTTP connection parameters. These instead rely on STOMP protocol’s CONNECT Frame. This frame can have headers as key/value pairs. You can control these by setting connectHeaders configuration option. You can pass any pair of strings as keys and values.

So, typically, for token-based authentication you will pass the token as part of connectHeaders. Check your broker documentation for details.

If you are using Spring, please check https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#websocket-stomp-authentication-token-based

Q: My authentication tokens expire, where should I write code to acquire fresh tokens?

The suggested place to acquire fresh tokens is beforeConnect callback. You can update the connectHeaders after you have acquired a fresh token.

If you need to fetch a token using an async request (say using an XHR), you can set an async function as the callback.

NodeJS

Q: Can this library be used with NodeJS?

Yes, NodeJS is supported using WebSockets as the communication mechanism. Please see NodeJS topic in using StompJS guide. In addition, check the needed PolyFills.

While this library can be used with NodeJS, if your broker supports, you should consider AMQP or MQTT. These protocols are likely to give more flexibility than STOMP.

React Native

Q: I am using it with React Native, I have started facing strange issues?

Please see React Native - Additional Notes.

Jeff Mesnil's stompjs

Q: How do I migrate from Jeff Mesnil's stompjs?

Please see upgrading stompjs guide.

The v4 of this library is backwards compatible with the original stompjs. In all likelihoods your working code would work under compatibility mode of v5.

To use newer features like automatic reconnection, compliance with STOMP standards, and binary payloads, you would need to upgrade to newer syntax.

Q: Are there any missing features from Jeff Mesnil's stompjs?

Jeff Mesnil’s stompjs supports STOMP over TCP when used in the NodeJS environment. Other than this, there is no known missing functionality. If you intend to use this feature, please raise an issue.

Jeff Mesnil’s stompjs is not fully compliant to STOMP protocol. The @stomp/stompjs strictly adheres the protocol. This might, in some cases, give behavioral differences. If you are facing any such issues, please raise an issue.

Updated: