StompJS

STOMP library for JavaScript/TypeScript.

Upgrading StompJs

3 minute read

Upgrading from version 3/4

Important: For NodeJS and React Native, please check Polyfills.

Basic changes

Please follow section Include STOMP.js to add the latest version.

The following is for convenience, — to keep the code change to the minimum.

// Depending on your JS version you may have to use var instead of const

// To use compatibility mode
const Stomp = StompJs.Stomp;

For the lazy: use the compatibility mode

With the changes above, your code should now work. If you face issues, please raise an issue at https://github.com/stomp-js/stompjs/issues.

Note: no new features will be added to the compatibility mode. Attempt would be made so that code working in version 3/4 continues to work. The compatibility mode will be maintained till 2020.

Take control: proper upgrade

This section covers the rationale of new features and changes needed to take full advantage.

Creating a client and connecting

In version 3/4, typically, a client instance is created and one of the variants of connect is called. Over the years, connect has gotten many variants with a different combination of parameters.

The new version makes all options settable on client instance. These options can be passed during creation of a client or while calling client.activate.

Old

const client = Stomp.client('ws://localhost:15674/ws');

client.debug = function (str) {
  console.log(str);
};

client.heartbeat.incoming = 4000;
client.heartbeat.outgoing = 4000;

client.reconnect_delay = 5000;

client.connect('user', 'password', function () {
  // Do something
});

Updated

const client = new StompJs.Client({
  brokerURL: 'ws://localhost:15674/ws',
  connectHeaders: {
    login: 'user',
    passcode: 'password',
  },
  debug: function (str) {
    console.log(str);
  },
  reconnectDelay: 5000,
  heartbeatIncoming: 4000,
  heartbeatOutgoing: 4000,
});

client.onConnect = function (frame) {
  // Do something
};

client.activate();

Please see StompConfig for all possible options. These options can be set onto client. Alternatively, these can be passed as options to the Client constructor constructor, the Client#activate or the Client#deactivate calls. If you want to set options in bulk, you can use Client#configure.

Publishing messages

Old

client.send('/topic/general', {}, 'Hello world');

// Skip content length header
client.send('/topic/general', { 'content-length': false }, 'Hello world');

// Additional headers
client.send('/topic/general', { priority: '9' }, 'Hello world');

Updated

client.publish({ destination: '/topic/general', body: 'Hello world' });

// There is an option to skip content length header
client.publish({
  destination: '/topic/general',
  body: 'Hello world',
  skipContentLengthHeader: true,
});

// Additional headers
client.publish({
  destination: '/topic/general',
  body: 'Hello world',
  headers: { priority: '9' },
});

Semantic changes

Name changes

These changes have been carried out in order to make a consistent naming convention (lowerCamelCase) and to make the meaning of the option clearer.

Dropped APIs

  • maxWebSocketFrameSize — large messages work without this. Test cases have been added to test large text and binary messages.

Migrating from Version 2

You will need to follow the instructions above with few additional considerations.

Please note:

  • Auto reconnect is switched on by default. Set Client#reconnectDelay to 0 to disable.
  • After each connect (i.e., the initial connect as well each reconnection) the Client#onConnect (connectCallback in earlier versions) will be called.
  • After reconnecting, it will not automatically subscribe to queues that were subscribed. So, if all subscriptions are part of the Client#onConnect (which it would in most of the cases), you will not need to do any additional handling.

Additional notes:

  • Stomp.overWS is same as Stomp.client. Follow the instructions for Stomp.client above.
  • NodeJS is supported at same level as browser. Test suits are executed for both NodJS and browser. Follow the instructions as above.
  • Stomp.overTCP is no longer supported. If your broker supports WebStomp (STOMP over WebSocket), you may switch to that.
  • If you are using SockJS please also see SockJS support

Updated: