Frequently Asked Questions

7 minute read

Under heavy construction

General

Q: What are STOMP and WebStomp?

STOMP is a very simple text protocol to interact with messaging brokers. Typically 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.

Further web browsers do not allow TCP connections from web pages. Thankfully these support WebSockets. This library implements STOMP protocol over WebSockets, which is sometimes referred as WebStomp.

Q: What documentation is available?

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

stompjs is the core underlying library, usable almost everywhere.

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

ng2-stompjs offers same functionally as rx-stomp. ng2-stompjs makes rx-stomp classes Injectable and sets up some factories. If you are using Angular you should consider this variant.

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

Yes.

These libraries are released as UMD. This should allow these modules to be used as JavaScript on web page as well as from variety of module systems.

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

In the bundle, ESM5 and ESM6 variants are also included, which can be used as alternatives.

Q: I am using Angular, which of stompjs, rx-stomp, or ng2-stompjs should I use?

Angular makes heavy use of RxJS, Using rx-stomp or ng2-stompjs should feel natural with Angular.

If you are going to use Angular Dependency Injection, ng2-stompjs would be the way to go. ng2-stompjs makes rx-stomp classes Injectable and sets up some factories.

Having said all of these, you can actually 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.

The versions - stomp-js@6, rx-stomp@1, ng2-stompjs@8 - are targeted to es2015. This ensures smaller code size. The code follows guidelines that should allow proper tree shaking behavior.

rx-stomp, prior to v1, was distributed as commonjs modules, which may not be tree shaking friendly. Please upgrade if you face issues.

Q: What are Heartbeats? Should I bother?

Most of STOMP 1.1+ brokers will support heart beats. These can be broker to the client (incoming) or client to the broker (outgoing). When enabled periodic heat beats are sent. If heart beats 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 the disconnections 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 Heart Beats topic on how to use it.

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

Q: Help me, I am getting errors about missing Object.assign

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 has 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 header key/value pairs. You can control these by setting connectHeaders configuration option. You can pass any pair of strings as key 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 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 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?

Jeff Mesnil's stompjs

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

Please see upgrading stompjs guide.

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

To use newer features like automatic reconnection, 100% 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?

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

The Jeff Mesnil’s stompjs does not support the STOMP protocol strictly while @stomp/stompjs implements the protocol strictly and completely. This might, in some cases, give behavioral differences. If you facing any such issues please raise an issue.

Updated: