STOMP library for JavaScript/TypeScript.

4 minute read

Upgrading from version 3/4

Important: For Node.js 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 (UMD build via <script>)
const Stomp = StompJs.Stomp;

CommonJS require is not supported; use ES module imports in Node.js or bundlers.

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 (UMD via 

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();

Updated (ES modules)

import { Client } from '@stomp/stompjs';

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

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

client.activate();

To disconnect and stop reconnection attempts, call Client#deactivate. This method is asynchronous; prefer awaiting it to avoid races:

await client.deactivate();

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, 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.
  • Node.js is supported at same level as browser. Test suites are executed for both Node.js and browser. Follow the instructions as above.
  • Stomp.overTCP is no longer supported by this library. However, you can use TCP Wrapper.
  • If you are using SockJS please also see SockJS support

Updated: