{"id":15701,"library":"message-bus-client","title":"MessageBus JavaScript Client","description":"The `message-bus-client` package is the official JavaScript client library for connecting to the Ruby `message_bus` server. It provides robust functionalities for subscribing to channels, receiving real-time messages via polling, long-polling, or long-polling with streaming, and managing subscriptions and message backlogs. Designed to work seamlessly with the `message_bus` Ruby gem, which acts as a Rack middleware, it enables scalable concurrent connections. The current stable version is 4.5.2, reflecting active maintenance, as it is a critical component of Discourse, where it's used in production at scale. Its primary role is to establish a reliable client-server communication channel for web applications.","status":"active","version":"4.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/discourse/message_bus","tags":["javascript","es6","modules"],"install":[{"cmd":"npm install message-bus-client","lang":"bash","label":"npm"},{"cmd":"yarn add message-bus-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add message-bus-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"MessageBus is a named export, not a default export. This is the primary way to import the client in modern JavaScript environments.","wrong":"import MessageBus from 'message-bus-client';","symbol":"MessageBus","correct":"import { MessageBus } from 'message-bus-client';"},{"note":"For CommonJS environments, the MessageBus class is a named export and should be destructured from the require call.","wrong":"const MessageBus = require('message-bus-client');","symbol":"MessageBus","correct":"const { MessageBus } = require('message-bus-client');"},{"note":"This is a type-only import for TypeScript users to define the constructor options for the MessageBus client instance.","wrong":"import { MessageBusOptions } from 'message-bus-client';","symbol":"MessageBusOptions","correct":"import type { MessageBusOptions } from 'message-bus-client';"}],"quickstart":{"code":"import { MessageBus } from 'message-bus-client';\n\n// Configure the MessageBus client with your server's base URL if different from current origin\nconst bus = new MessageBus({\n  baseUrl: 'http://localhost:9292/message-bus' // Replace with your MessageBus server URL\n});\n\nbus.start(); // Start polling for messages immediately\n\nbus.subscribe('/global-channel', (data, messageId) => {\n  console.log(`Received message on /global-channel (ID: ${messageId}):`, data);\n});\n\nbus.subscribe('/user-channel-123', (data) => {\n  console.log('Received targeted message:', data);\n});\n\n// To stop listening and disconnect\n// setTimeout(() => {\n//   bus.unsubscribe('/global-channel');\n//   bus.stop();\n//   console.log('MessageBus stopped and unsubscribed.');\n// }, 60000);\n","lang":"javascript","description":"Demonstrates how to initialize the MessageBus client, subscribe to multiple channels, and receive real-time messages. It includes optional server URL configuration."},"warnings":[{"fix":"Ensure your MessageBus server application is running on Ruby 3.2 or a newer officially supported Ruby version. Consult the Ruby gem's documentation for current support policies.","message":"The upstream MessageBus Ruby gem (server-side component) officially supports Ruby versions 3.2 and up as of March 2025. Running the server with older, unsupported Ruby versions may lead to compatibility issues or unexpected behavior with the JavaScript client.","severity":"breaking","affected_versions":">=4.0"},{"fix":"Refer to the MessageBus Ruby gem's documentation for detailed server setup instructions, especially regarding Rack Hijack and web server configurations (Puma, Unicorn, Thin, Passenger) to ensure efficient long-polling.","message":"Optimal performance and concurrent long-polling for the MessageBus server (Ruby gem) heavily rely on specific Rack middleware and web server configurations (e.g., Rack Hijack, Thin::Async). Improper server setup can significantly degrade performance or cause connection instability for clients.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Review the release notes for both `message-bus-client` and the `message_bus` Ruby gem before upgrading. Aim to keep both components on closely matched or explicitly compatible major versions to avoid synchronization issues.","message":"Significant version discrepancies between the `message-bus-client` and the `message_bus` Ruby gem can lead to unexpected behavior, connection failures, or protocol mismatches. It is generally recommended to keep both components updated to compatible versions.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Configure your MessageBus server (Rack application) to include appropriate `Access-Control-Allow-Origin` headers that permit requests from your client's domain. Tools like `rack-cors` can simplify this configuration in Ruby applications.","message":"If the `message-bus-client` is deployed on a different domain or port than the `message_bus` server, Cross-Origin Resource Sharing (CORS) headers must be properly configured on the server. Failure to do so will result in browser security errors blocking client-server communication.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify that your MessageBus server (Ruby application) is actively running and reachable from the client's network. Check server logs for startup errors and ensure the `baseUrl` configured in the client matches the server's address.","cause":"The MessageBus server is not running, is inaccessible at the specified URL, or a firewall is blocking the connection.","error":"GET http://your-messagebus-server.com/message-bus/poll net::ERR_CONNECTION_REFUSED"},{"fix":"On the MessageBus server, configure CORS to allow requests from your client's domain (e.g., `http://your-client-domain.com`). This typically involves adding middleware like `rack-cors` in Ruby Rack applications.","cause":"The browser is enforcing its Same-Origin Policy, and the MessageBus server has not sent the necessary `Access-Control-Allow-Origin` header allowing requests from your client's domain.","error":"Access to fetch at 'http://your-messagebus-server.com/message-bus/poll' from origin 'http://your-client-domain.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource."},{"fix":"Ensure that `MessageBus` is instantiated correctly with `new`: `const bus = new MessageBus();`.","cause":"This error occurs when attempting to invoke `MessageBus` as a function instead of instantiating it as a class using the `new` keyword.","error":"TypeError: MessageBus is not a constructor"}],"ecosystem":"npm"}