[NO LONGER MAINTAINED] node framework for stomp over websockets
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Read about STOMP protocol here.

It seems STOMP is under-appreciated for realtime apps. It's text-based so it can work over WebSocket connections. My hope is to provide enough structure to make STOMP servers as simple as express HTTP servers.

The motivation for using STOMP instead of socket.io or SocketCluster or Sails or ActionCable is that STOMP is an open protocol which can run on any client or server the supports TCP connections. Things change, perhaps in the future you'll want to use golang on the server and native iOS sockets.

Each package module is explained below, from lowest to highest abstraction.


Each message between client and server is a "frame", which looks like:

var frame = {
  command: "string",
  headers: { "string": "string" },
  body: "string",

var text = Frame.toString(frame)
frame = Frame.fromString(text)

The STOMP protocol defines available commands and headers. webstomp checks if the command is valid.


The webstomp Socket encodes and decodes frames. Otherwise, you'd have to call toString and fromString on each send and receive.

var WebSocket = require("ws")
var {Socket} = require("webstomp")

var ws = new WebSocket("https://example.com")
var socket = new Socket(ws)

socket.on("message", function (frame) {
  // Frame objects emitted here

socket.send({ command, headers, body }, function (err) {
  // Sends encoded text frame
  if (err) {
    // Failed to send :(


The webstomp Server emits Socket connections. Otherwise, you'd have to wrap each new WebSocket connection yourself.

var {Server} = require("webstomp")

var server = new Server({ port: 8000 })
server.on("connection", function (socket) {
  // Socket is a webstomp Socket

You're bored. Here's the useful bits coming up.


The webstomp Session adds a number of helpers. Otherwise you'd have to send full frames and stringify javascript objects.

var {Session} = require("webstomp")

// `socket` is a webstomp Socket
var session = new Session(socket)

// Send connected frame
session.connected({ session: "session-id-123", server: "OurCompany/3.4" })

// Send json message to a channel
var data = { key: "value" }
var headers = { "channel": "/notifications" }
session.message(data, headers)

// Send errors to client
session.error(new Error("sharp edges"))

For realtime apps, it's practical to model channels as lazy observables. Sessions can pipe observable events to the client as message frames. Examples include es-observable, kefir or baconjs stream, readable event-stream, etc.

// When client subscribes
var unhook = session.observe(stream, { "channel": "/notifications" })

// When client unsubscribes


The webstomp Router is designed to look like express. Instead of HTTP actions, you have STOMP actions. Instead of (req, res, next) you have this (next).

var {Router} = require("webstomp")

var router = new Router()

router.use(function (next) {
  // proceed to next
  // halt on error
  next(new Error("colors not coordinated"))

router.connect(function () {
  // Context is `this`
  // Keep track of stuff between frames on the `state` object. 
  var {email, passcode} = this.headers
  this.state.user = authenticate(email, passcode)
  // The current client session is available on `this` as well

router.send("/users/:id/messages", function () {
  var {id} = this.params
  this.error(new Error("Invalid id: " + id))

router.subscribe("/stats/:metric", function () {
  var stream = service.getChanges()



The webstomp App ties it all together. It creates a WebSocket server, wraps it with a webstomp Server, acts like a webstomp Router, and dispatches request Frames to the current Session.

var {App} = require("webstomp")
var app = new App()

// Or you can be fancy
// var app = require("stomp")()


app.use(function () {
  this.error(new Error("Not found"))


Mount Server

You can mount a webstomp App onto an HTTP server, which allows you to use the HTTP server too. For example, with express:

var http = require("http")
var stomp = require("webstomp")()
var api = require("express")()

var server = stomp.mount({
  server: http.createServer(api)

server.listen(port, function () {
  console.log("open for business")

So that's it. For realtime apps, on-demand PUB/SUB channels provide structure. The pattern maps well to server-side services that return an observable, and also client-side components that subscribe when added into view, and unsubscribe when removed.

Open Source

Please contribute ideas, bugs, etc.

MIT License