STOMP library for JavaScript/TypeScript.

8 minute read

Under heavy construction

General

Q: What are STOMP and WebStomp?

STOMP is a simple text protocol for messaging brokers. Implementing broker-native protocols like AMQP, MQTT, or JMS in JavaScript can be complex; STOMP is a practical alternative.

Browsers do not allow raw TCP connections from web pages. To overcome this, many brokers support STOMP over WebSocket, commonly called WebStomp.

Q: What documentation is available?

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

stompjs is the core library.

rx-stomp exposes functionality as RxJS primitives. If you already use RxJS or prefer reactive streams, consider rx-stomp.

A key difference: with stompjs, use the client primarily inside the onConnect callback; using it outside can lead to races. rx-stomp avoids this limitation.

Rule of thumb: if you need to interact with the client outside the connect lifecycle, prefer rx-stomp. With Angular (which relies heavily on RxJS), rx-stomp feels natural.

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

Yes.

These libraries are distributed as JavaScript ES Modules by default and can be imported with import.

All libraries are developed in TypeScript and include type definitions.

A UMD bundle is also provided for direct use via a <script> tag in browsers.

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.

Angular makes heavy use of RxJS, so rx-stomp is the recommended choice for Angular apps.

Why rx-stomp:

  • Native RxJS APIs (Observables) for messages, connection state, and lifecycles.
  • Subscriptions auto-reestablish on reconnects without manual bookkeeping.
  • Works well with Angular patterns (services, dependency injection, async pipes).

When to use stompjs:

  • You want the lightest possible dependency set and prefer imperative APIs.
  • You are not using RxJS in your app.

Helpful links:

  • Angular sample using @stomp/rx-stomp: https://github.com/stomp-js/rx-stomp-angular
  • Migrating from ng2-stompjs to rx-stomp: {% link _posts/2022-03-03-ng2-stompjs-to-rx-stomp.md %}

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

Yes.

The packages ship ES modules compatible with modern bundlers (e.g., Vite, Rollup, Webpack, Parcel). Tree-shaking works well when you import the specific symbols you need.

Q: Do these libraries work well with tree shaking?

Yes — when you consume them as ES modules.

Tips for best results:

  • Use ESM and named imports: 
    import { Client } from '@stomp/stompjs';
// good: only Client is bundled

    Avoid wildcard or UMD usage in apps you intend to tree-shake:

    // avoid for app bundles (prevents effective tree-shaking)
// import * as StompJs from '@stomp/stompjs';
// <script src=".../stomp.umd.js"></script>
  • Import only what you use; don’t re-export the entire package from your own index.
  • Build in production mode so your bundler can perform dead-code elimination.
    • Webpack: mode: 'production' (enables optimization.usedExports)
    • Rollup/Vite/Parcel: production builds enable tree-shaking by default
  • Keep “side-effect free” usage:
    • Prefer top-level imports of symbols you actually use over side-effect-only imports.
  • Verify with a bundle analyzer (e.g., webpack-bundle-analyzer, rollup-plugin-visualizer).

Note:

  • The UMD bundle is intended for direct <script> use in browsers and is not tree‑shakeable.
  • If you still see unexpected code retained, ensure all dependencies and your bundler are up to date and that you’re not pulling the UMD build accidentally.

Q: What are heartbeats? Should I bother?

Most STOMP 1.1+ brokers support heartbeats — periodic pings either from the broker to the client (incoming) or the client to the broker (outgoing). If heartbeats are not received within a configured time (plus grace), the connection is considered stale and closed.

SockJS may not support heartbeats with some brokers. See {% link _posts/2018-09-10-using-stomp-with-sockjs.md %}.

Whether you should enable heartbeats depends on your needs:

  • Pro: stale connections are detected sooner.
  • Con: small packets continue even when there is no app traffic.

See the Heart-beating section for usage details: {% link _posts/2018-06-29-using-stompjs-v5.md %}#heart-beating

Q: How do I enable logging?

See the Debug section in the guide: {% link _posts/2018-06-29-using-stompjs-v5.md %}#debug

The console debug output may contain NULL characters, which can break copy/paste into an issue. If that happens, save the output to a text file and attach it to the issue.

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

Please see the Polyfills guide: {% link _posts/2018-06-28-polyfills-for-stompjs.md %}

  • Node.js: provide a WebSocket implementation and ensure TextEncoder/TextDecoder exist.
  • React Native: add TextEncoder/TextDecoder; WebSocket is provided by RN.
  • Browsers: typically no polyfills are required.

SockJS

Q: Is SockJS needed to use these libraries?

No. SockJS is optional.

Prefer native WebSockets by default. Use SockJS only to support environments without WebSocket, or when your deployment requires HTTP-only transport.

See: {% link _posts/2018-09-10-using-stomp-with-sockjs.md %}

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

Pass a webSocketFactory that creates a new SockJS instance for each (re)connect.

See: {% link _posts/2018-09-10-using-stomp-with-sockjs.md %}

If you are using the legacy Stomp.over compatibility API, refer to Stomp.over API docs.

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

See the guide: {% link _posts/2018-09-10-using-stomp-with-sockjs.md %}

Authentication

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

While WebSocket is initiated via HTTP(S), custom headers cannot be set during the handshake.

STOMP brokers typically expect authentication in the STOMP CONNECT frame via headers. You can supply arbitrary key/value pairs using connectHeaders.

For token-based authentication, include your token in connectHeaders as required by your broker. If using Spring, see: https://docs.spring.io/spring-framework/reference/web/websocket/stomp/authentication.html#websocket-stomp-authentication-token-based

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

Use the beforeConnect callback to fetch a fresh token and update connectHeaders just before each (re)connect.

If you need async fetching (e.g., HTTP call), make beforeConnect an async function.

NodeJS

Q: Can this library be used with NodeJS?

Yes. Node.js is supported using WebSockets as the transport. See the guide: {% link _posts/2018-06-29-using-stompjs-v5.md %}

Also ensure required polyfills are present: {% link _posts/2018-06-28-polyfills-for-stompjs.md %}

If your broker supports them, you may also consider broker-native protocols like AMQP or MQTT.

React Native

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

The largest number of issues reported are related to React Native. These are platform/runtime limitations or environment problems — not bugs in this library.

Please read and follow the React Native guide before reporting issues:

  • {% link _posts/2019-06-10-react-native-additional-notes.md %}

This library requires specific workarounds to function correctly with React Native; the guide documents those steps. If problems persist after following the guide, include your RN version, platform (iOS/Android), relevant configuration, and logs when opening an issue.

Jeff Mesnil's stompjs

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

See the upgrade guide: {% link _posts/2018-09-08-upgrading-stompjs.md %}

v4 provides compatibility with the original stompjs. For newer features (auto-reconnect, full STOMP compliance, binary payloads), migrate to the v5+ API.

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

The original stompjs offered STOMP over TCP in Node.js. @stomp/stompjs focuses on STOMP over WebSocket (WebStomp), which is supported by most brokers.

@stomp/stompjs adheres more strictly to the STOMP specification than the original library, so behavior may differ in edge cases. If you hit issues, please raise an issue.

If you specifically need STOMP over TCP in Node.js, consider using the TCP Wrapper: https://github.com/stomp-js/tcp-wrapper

Updated: