stomp.js for node.js apps

stomp.js is a simple JavaScript library to send and receive STOMP messages from a Web browser using Web Sockets.

Today, I have released its version 2.3.0 that adds support for node.js. This makes it possible to send and receive STOMP message from any node.js app by connecting to a STOMP broker on its TCP port (usually 61613) or on its Web Socket.

I have registered a npm package stompjs that can be installed by typing:

npm install stompjs

and in the code, requiring the module:

var Stomp = require('stompjs');

To connect to a STOMP broker over a TCP socket, use the Stomp.overTCP(host, port) method:

var client = Stomp.overTCP('localhost', 61613);

To connect to a STOMP broker over a Web Socket, use instead the Stomp.overWS(url) method:

var client = Stomp.overWS('ws://localhost:61614/stomp');

Apart from this initialization, the STOMP API remains the same whether it is running in a Web browser or in node.js application.

A simple node.js app that sends and receives a STOMP message can be coded in a few lines:

var Stomp = require('stompjs');

// Use raw TCP sockets
var client = Stomp.overTCP('localhost', 61613);
// uncomment to print out the STOMP frames
// client.debug = console.log;

client.connect('user', 'password', function(frame) {
  console.log('connected to Stomp');

  client.subscribe('/queue/myqueue', function(message) {
    console.log("received message " + message.body);

    // once we get a message, the client disconnects
    client.disconnect();
  });
  
  console.log ('sending a message');
  client.send('/queue/myqueue', {}, 'Hello, node.js!');
});

In this example, the client connect to the STOMP broker on its TCP socket by calling Stomp.overTCP(host, port):

var client = Stomp.overTCP('localhost', 61613);

To connect on its Web Socket, you only need to change the creation of the client by calling instead Stomp.overWS(url):

var client = Stomp.overWS('ws://localhost:61614');

This means that if your code uses stomp.js, you can run the same code in the Web browser or in node.js That may prove handy for testing...

Why another STOMP client for node.js when there are already a dozen?

I believe the code of stomp.js is already the best of them.

It is distributed by the major STOMP brokers (ActiveMQ, Apollo, HornetQ, and RabbitMQ), widely used, thoroughly tested and documented.

The STOMP protocol implementation is the same whether the client is running in a Web browser or in node.js. The only differences are the timers and the socket implementations (native Web Socket for Web browser, net.Socket for node.js). The socket implementation can still be customized and many users run it over SockJS

There are likely some corner cases to iron out but the main features (including heart-beating) should work as expected.

Note that the node.js support is done outside the stomp.js file. If you only need to use STOMP from the Web browser, this changes nothing: you only need that file (or its minified version).

Enjoy!