@rails/actioncable

@rails/actioncable is the browser-side JavaScript client for Action Cable, the full-stack WebSocket framework shipped as part of Ruby on Rails. It establishes and maintains a single WebSocket connection to a Rails server, then lets an app create per-feature Subscriptions to server-defined Channel classes — the same organizing pattern Rails uses for HTTP controllers, but for long-lived, bidirectional connections.

On the server, Channel classes handle subscribe/unsubscribe lifecycle events and expose public methods the client can invoke, while broadcasts fan out to subscribers through a pluggable adapter (Redis, PostgreSQL LISTEN/NOTIFY, in-process async, or a synchronous inline adapter for tests) — letting a Rails app move from single-process development to a horizontally-scaled deployment without changing Channel code. This npm package is published from the same rails/rails monorepo as the Ruby gem, and versions in lockstep with it.

What You Get

• The @rails/actioncable npm package: a small JS client (Consumer/Connection/Subscriptions) for connecting to and subscribing on an Action Cable server
• Automatic connection monitoring and reconnection via ConnectionMonitor, with configurable stale-connection thresholds
• A symmetric server-side Ruby framework (the actioncable gem, published alongside this npm package from the same rails/rails monorepo) providing Channel base classes and pluggable broadcast adapters
• Rails generators (rails generate channel) that scaffold matching server Channel and client subscription boilerplate

Common Use Cases

• Real-time chat, notifications, and presence indicators in a Rails app
• Live-updating dashboards and activity feeds driven by background jobs
• Collaborative multi-user features like shared live-editing indicators
• Streaming updates from model callbacks or Active Job out to subscribed clients

Under The Hood

Architecture Action Cable follows a layered pub/sub architecture split across client (JS) and server (Ruby) halves that communicate over a WebSocket protocol. On the server, engine.rb registers the Rails engine, server/base.rb boots a connection manager backed by a server/worker.rb thread pool and server/connections.rb registry; incoming socket frames are parsed in server/socket.rb via nio4r/websocket-driver into JSON messages routed to channel/base.rb subclasses, which mirror ActionController semantics (subscribed/unsubscribed lifecycle callbacks, action dispatch via public methods). Broadcasting fans out through pluggable subscription_adapter/* adapters (redis.rb, postgresql.rb, async.rb, inline.rb) implementing a common Base interface with a SubscriberMap for thread-safe subscriber bookkeeping — this is the core abstraction whose replacement requires no changes to Channel code. The client (app/javascript/action_cable/*) is a parallel state machine: Consumer owns a Connection (WebSocket lifecycle plus reconnect via ConnectionMonitor heartbeats) and a Subscriptions registry managing Subscription instances; message dispatch in connection.js switches on a small message_types protocol (welcome/disconnect/ping/confirmation/rejection) to drive subscription lifecycle callbacks.

Tech Stack The package ships as a dual-runtime component — the npm package (built from app/javascript/action_cable via Rollup into a UMD bundle and an ESM build) plus the actioncable RubyGem, which requires activesupport/actionpack at the exact same Rails version, nio4r for socket I/O, websocket-driver for the WebSocket handshake/framing, and zeitwerk for autoloading. Pluggable pub/sub backends are represented by the subscription_adapter classes — Redis via the redis-client gem, Postgres via LISTEN/NOTIFY. JS-side tooling uses a flat ESLint config for linting and the web-test-runner plus QUnit and mock-socket for browser tests, built and versioned from the same rails/rails monorepo as every other Rails framework component.

Code Quality Extensive dual-language test coverage exists — the Ruby side has dozens of test files across connection/, channel/, server/, and subscription_adapter/ directories, using Rails’ own test-case conventions plus a purpose-built Channel/Connection TestCase and test helper that ships as public API for consumers to test their own channels. The JS side has its own unit tests run through web-test-runner and QUnit with mock-socket standing in for real WebSocket objects. Error handling is explicit and deliberate, with inline comments explaining tricky concurrency edge cases (such as recovering a dead listener thread) and retry/backoff logic around dropped Redis connections. Naming is consistently Rails-idiomatic in Ruby and conventional in JS. Neither language layer is statically typed, but the surrounding rails/rails monorepo runs a full CI matrix against every change.

API Design Action Cable’s developer-experience contribution is making full-duplex realtime feel like ordinary Rails MVC: a Channel class mirrors a Controller (public methods become callable client actions, subscribed/unsubscribed act as lifecycle hooks), and the client API mirrors this symmetry when creating a subscription and defining its received callback. The pluggable adapter layer (Redis/Postgres/async/inline) behind that same Channel abstraction is what lets identical application code scale from a single dev box to a distributed, Redis-backed fleet with no code changes — a meaningful ergonomic win over hand-rolling raw WebSocket handlers, even though the underlying WebSocket and pub/sub technology itself is standard.