Action Cable

5.2.8-1 verified Sat Apr 25 auth: no javascript

Action Cable is the WebSocket framework integrated into Ruby on Rails, providing real-time communication capabilities for Rails applications. The npm package 'actioncable' (current stable version 5.2.8-1, though the Rails ecosystem recommends using the latest 7.x or 8.x series) is the JavaScript client library that connects to an Action Cable server. It allows developers to subscribe to channels and receive broadcasts in the browser or any JavaScript runtime. Key differentiators: tight integration with Rails (session/cookie-based authentication, same MVC patterns), full-stack offering with both server- and client-side components, and pub-sub streaming model. Release cadence follows Rails releases, with frequent minor and patch updates. Alternatives include pure WebSocket libraries or Pusher, but Action Cable is the default for Rails real-time features.

Common errors

error WebSocket is not defined ↓

cause Running in Node.js environment where WebSocket is not globally available.

fix

Install the 'ws' package and add: global.WebSocket = require('ws'); before importing ActionCable.

error Module not found: Can't resolve '@rails/actioncable' ↓

cause Importing from deprecated package name @rails/actioncable.

fix

Change import to 'actioncable'.

error TypeError: ActionCable.createConsumer is not a function ↓

cause Using the wrong import (e.g., importing default incorrectly or using a very old version).

fix

Use import ActionCable from 'actioncable' for default import, and ensure the version is >=5.0.0.

error Cannot find module 'actioncable' or its corresponding type declarations. ↓

cause TypeScript cannot find type definitions.

fix

Install @types/actioncable as a devDependency: npm install --save-dev @types/actioncable.

Warnings

breaking ActionCable.createConsumer() no longer accepts a function as argument; must pass a URL string or omit for default. ↓

fix Pass a string URL or call without arguments to use the default from meta tags.

deprecated The package @rails/actioncable (npm) is deprecated in favor of the actioncable package (npm). ↓

fix Use import from 'actioncable' instead of '@rails/actioncable'. Both publish the same code, but actioncable is the canonical name.

gotcha Importing 'actioncable' in Node.js without a WebSocket polyfill will throw: 'WebSocket is not defined'. ↓

fix Install 'ws' package and set global.WebSocket = require('ws'); or use a bundler that polyfills WebSocket.

gotcha TypeScript definitions are not included; you must install @types/actioncable separately. ↓

fix Run 'npm install --save-dev @types/actioncable' to get type definitions.

breaking ActionCable.Connection and ActionCable.Subscription are no longer publicly accessible; use createConsumer and subscriptions.create. ↓

fix Use the top-level API: ActionCable.createConsumer() and subscription methods.

Install

npm install actioncable

yarn add actioncable

pnpm add actioncable

Imports

ActionCable
wrong
```
const ActionCable = require('actioncable')
```
correct
```
import ActionCable from 'actioncable'
```
Default import works with both ESM and CJS environments. For TypeScript, use `import ActionCable from 'actioncable'` with esModuleInterop enabled.
createConsumer
wrong
```
import { createConsumer } from '@rails/actioncable'
```
correct
```
import { createConsumer } from 'actioncable'
```
Named export available since v5.2.0. Prefer over default import for tree-shaking.
Consumer
wrong
```
import { Consumer } from 'actioncable'
```
correct
```
import type { Consumer } from 'actioncable'
```
Consumer is a TypeScript interface, not a class. Use type import to avoid runtime errors.
createWebSocketURL
wrong
```
import { createWebSocketURL } from 'actioncable/lib'
```
correct
```
import { createWebSocketURL } from 'actioncable'
```
Utility function for building WebSocket URLs. Import directly from package root.

Quickstart

Shows how to create a consumer, subscribe to a channel, handle lifecycle events, send data, and clean up.

import ActionCable from 'actioncable';

const cable = ActionCable.createConsumer('ws://localhost:3000/cable');
const subscription = cable.subscriptions.create('ChatChannel', {
  connected() {
    console.log('Connected to ChatChannel');
  },
  disconnected() {
    console.log('Disconnected');
  },
  received(data) {
    console.log('Received:', data);
  }
});

// Send data to server (requires server-side handling)
subscription.send({ message: 'Hello!' });

// Unsubscribe when done
subscription.unsubscribe();
cable.disconnect();