stompjs

STOMP.js is a full implementation of the STOMP protocol (versions 1.0, 1.1, and 1.2) over WebSocket, letting JavaScript and TypeScript applications talk directly to message brokers such as RabbitMQ and ActiveMQ. The library exposes a single Client class that manages the WebSocket connection lifecycle, heartbeats, and STOMP frame parsing, so application code only needs to configure a broker URL, subscribe to destinations, and publish messages.

It runs unmodified in both browser and Node.js environments — Node usage just requires assigning a WebSocket polyfill like ws to the global scope. The client handles automatic reconnection with configurable backoff, heartbeat-based dead-connection detection, binary payload support, and STOMP transactions/acks, making it suitable for production messaging use cases rather than toy demos.

For teams that prefer reactive/RxJS-style APIs, the same maintainers publish Rx-Stomp on top of this library, which wraps the imperative Client API in Observables. STOMP.js itself stays dependency-light and framework-agnostic, ships its own TypeScript type definitions, and is distributed as both an ESM package and a UMD bundle for direct <script> usage via import maps.

What You Get

• A Client class handling STOMP handshake, subscribe/publish, transactions, and acknowledgements
• Support for STOMP protocol versions 1.2, 1.1, and 1.0 with automatic version negotiation
• Automatic reconnection with configurable heartbeat and backoff behavior
• Binary payload support alongside plain-text STOMP frames
• Built-in TypeScript type definitions with no separate @types package needed
• Both ESM (esm6) and UMD browser bundles, usable via import maps or <script> tags

Common Use Cases

• Subscribing a browser dashboard to live RabbitMQ/ActiveMQ topic updates over WebSocket
• Publishing messages from a Node.js service to a STOMP-compliant broker using the ws polyfill
• Building chat, notification, or live-feed features backed by a message broker instead of a custom WebSocket protocol
• Layering Rx-Stomp on top for RxJS Observable-based subscription and publish streams

Under The Hood

Architecture The library is organized around a small set of focused modules under src/: client.ts (the public Client API and connection lifecycle), stomp-handler.ts (the STOMP protocol state machine that turns raw WebSocket frames into subscribe/publish/ack/transaction semantics), parser.ts (frame parsing/serialization), frame-impl.ts (the concrete IFrame/IMessage implementation), and ticker.ts (heartbeat timing). A compatibility/ directory preserves the older compat-client.ts/stomp.ts API surface for callers migrating from pre-v5 versions. This is a layered design: Client owns configuration and reconnection policy, delegates protocol mechanics to StompHandler, which in turn depends on Parser for wire-format concerns — changing the core Frame representation would ripple through stomp-handler.ts and the compatibility layer, but application code interacting only with Client would be insulated.

Tech Stack Written in strict-mode TypeScript targeting ES2020, compiled with tsc for the ESM (esm6) output and bundled separately via Rollup (@rollup/plugin-typescript, @rollup/plugin-terser) into a minified UMD bundle for direct browser <script> use. The package has zero runtime dependencies — devDependencies are limited to build/test tooling (typescript, rollup, eslint/typescript-eslint, prettier, sinon, ws, and Playwright for test execution). It ships as a native ES module ("type": "module") with conditional exports for CJS/require (UMD bundle) versus ESM import (esm6 output).

Code Quality Tests live under spec/unit/ as 17+ dedicated spec files (connection, reconnect, heart-beat, subscription, transaction, parser, frame, ack, receipts, plus a compatibility subfolder), run through Playwright’s Node project rather than a traditional unit-test runner, giving real async/WebSocket-timing coverage. CI (GitHub Actions) runs the suite across Linux, macOS, and a dedicated Node.js workflow, plus a docs-refresh workflow that regenerates published API docs. Linting is enforced via ESLint with typescript-eslint recommended rules plus Prettier formatting; several stricter rules (no-explicit-any, no-unused-vars) are intentionally relaxed for the compatibility layer, noted inline as “consider later” rather than silently ignored.

What Makes It Unique Unlike generic WebSocket wrapper libraries, STOMP.js implements the actual STOMP wire protocol (frame format, version negotiation, transactions, ack/nack semantics) rather than leaving message framing to the application. Its dual distribution model — ESM package for bundlers plus a standalone UMD bundle usable via import maps with no build step — lets it serve both modern bundler-based apps and simple static pages equally well, while the separate compatibility module keeps legacy pre-v5 API consumers working without forking the codebase.