DOCSEARCHbyAlgolia
Submit Docs

STOMP.js

repository·develop·Indexed 21 days ago

https://github.com/stomp-js/stompjs

A comprehensive STOMP protocol implementation (v1.0, v1.1, and v1.2) for browser and Node.js environments. It facilitates communication with STOMP-compliant messaging brokers like RabbitMQ and ActiveMQ over WebSockets or TCP. The library supports binary payloads, built-in TypeScript definitions, and provides integration with RxJS via the rx-stomp library.

Tokens
10.7K
Snippets
41
Records
53
Agent score
73%

What's inside @stomp/stompjs

  1. Introduction to STOMP.js

    develop
    STOMP.js is a library for connecting to STOMP brokers over WebSocket or TCP. It implements the STOMP protocol specifications (v1.0, v1.1, and v1.2), making it compatible with brokers like RabbitMQ and ActiveMQ. It supports both browser and Node.js environments, binary payloads, and provides integration with RxJS via the rx-stomp library.

  4. Set up STOMP.js in a Browser

    develop

    To use STOMP.js directly in a browser without a build step, use an import map to resolve @stomp/stompjs and include es-module-shims to support ESM imports in older browsers.

    <script type="importmap">
  {
    "imports": {
      "@stomp/stompjs": "https://ga.jspm.io/npm:@stomp/stompjs@7.0.0/esm6/index.js"
    }
  }
</script>
<script
  async
  src="https://ga.jspm.io/npm:es-module-shims@1.5.1/dist/es-module-shims.js"
  crossorigin="anonymous"
></script>

  5. Run tests in NodeJS or Browsers

    develop

    You can run the test suite in two different environments:

    • NodeJS: Runs tests using Jasmine. Use npm run test.
    • Browsers: Runs tests using Karma and Chrome. Use npm run karma.

    Caution: Both NodeJS and browser tests use the same set of test cases and the same queue names. Running both environments simultaneously may cause unexpected test failures due to resource contention on the broker.

    # Run tests in NodeJS
$ npm run test

# Run tests in Chrome via Karma
$ npm run karma

  6. Setup a RabbitMQ STOMP broker for testing

    develop

    Tests require a STOMP broker. The project provides a RabbitMQ configuration.

    Using Docker (Recommended)

    A Dockerfile is provided in the rabbitmq/ directory that includes the necessary plugins and configuration.

    1. Build the image: docker build -t myrabbitmq rabbitmq/
    2. Run the container: docker run -d -p 15674:15674 myrabbitmq

    Manual RabbitMQ Setup

    If using a local RabbitMQ installation:

    1. Enable the STOMP and WebStomp plugins.
    2. Configure RabbitMQ to use binary frames for WebStomp by adding the following to your rabbitmq.conf:
    echo 'web_stomp.ws_frame = binary' >> /etc/rabbitmq/rabbitmq.conf
    1. Update spec/config/browser-config.js and spec/config/node-config.js to match your specific broker setup (the defaults are configured for RabbitMQ on localhost).
    $ docker build -t myrabbitmq rabbitmq/
$ docker run -d -p 15674:15674 myrabbitmq

  8. Set up STOMP.js in Node.js

    develop

    To use STOMP.js in Node.js, you must install the @stomp/stompjs package along with a WebSocket implementation like ws. Because STOMP.js expects a global WebSocket object, you must manually assign the ws implementation to the global object.

    npm install @stomp/stompjs ws

  9. Use the deprecated Stomp class for legacy compatibility

    develop

    The Stomp class is a legacy factory used to create CompatClient instances. It is deprecated and will be removed in the next major version. Developers should migrate to the Client class using Client#brokerURL or Client#webSocketFactory instead.

    There are three primary ways to use this legacy class:

    1. Stomp.client(url, protocols): Creates a client connected to the STOMP server at the specified URL.
    2. Stomp.over(ws): An alternative to Stomp.client that allows specifying a custom WebSocket implementation or a factory function. To support auto-reconnection, you should pass a factory function that returns a new socket instance.
    3. Stomp.WebSocketClass: A static property used to globally set a non-standard WebSocket class (e.g., for Node.js environments). This approach is also deprecated.
    // Example: Using the legacy Stomp.client method
var url = "ws://localhost:61614/stomp";
var client = Stomp.client(url);

// Example: Using the legacy Stomp.over method with a factory for reconnection support
var client = Stomp.over(function() {
  return new WebSocket('ws://localhost:15674/ws');
});

  10. Use connectionTimeout for connection retries

    develop
    Introduced in version 6.0.0, the connectionTimeout configuration option allows the client to automatically retry a connection if it is not established within the specified timeframe. Note that in version 6.1.0, this feature is disabled by default to avoid conflicts with certain integrations.

  11. Configure exponential backoff and Web Workers for heartbeats

    develop

    Version 7.1.0 introduced two significant features for connection stability and performance:

    1. Exponential Backoff: The client now supports exponential backoff during reconnection attempts to avoid overwhelming the server.
    2. Web Worker Heartbeats: You can configure the client to use Web Workers for outgoing heartbeat pings, which can help prevent UI jank in browser environments.

  12. Configure WebSocket connection via brokerURL or webSocketFactory

    develop

    The client requires a way to establish a WebSocket connection. You can provide this in two ways:

    1. brokerURL: A string representing the WebSocket endpoint (e.g., ws://... or wss://...).
    2. webSocketFactory: A function that returns an IStompSocket (e.g., a native WebSocket or SockJS).

    Precedence: If both are provided, webSocketFactory takes precedence. This is useful for using polyfills like SockJS in environments without native WebSocket support.

    // Using brokerURL
client.brokerURL = 'ws://broker.domain.com:15674/ws';

// Using webSocketFactory (e.g., with SockJS)
client.webSocketFactory = function () {
  return new SockJS('http://broker.329broker.com/stomp');
};