Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createCableCarRoute
✓ import { createCableCarRoute } from 'redux-cablecar'
✗ const { createCableCarRoute } = require('redux-cablecar')
This is the primary factory function for creating the CableCar route and middleware. Modern applications typically use ESM `import`.
createMiddleware (via route instance)
✓ const cableCarRoute = createCableCarRoute(); const cableCarMiddleware = cableCarRoute.createMiddleware();
✗ import { createCableCarMiddleware } from 'redux-cablecar'
The middleware function itself is obtained by calling `createMiddleware()` on the `cableCarRoute` instance, not as a direct export.
connect (via route instance)
✓ cableCarRoute.connect(store, 'MainChannel', options)
✗ import { connect } from 'redux-cablecar'
The `connect` method is invoked on the `cableCarRoute` instance to establish the WebSocket connection with ActionCable, rather than being a standalone import.
This quickstart demonstrates the full setup of `redux-cablecar` by creating a Redux store using Redux Toolkit, applying the CableCar middleware, connecting to a simulated Rails ActionCable 'MainChannel' with custom parameters and action filtering, and dispatching an action intended for the server. It also shows an example of a local action not sent to the server.
import { configureStore } from '@reduxjs/toolkit';
import { createCableCarRoute } from 'redux-cablecar';
// A dummy reducer for demonstration purposes
const initialState = { messages: [] };
function reducer(state = initialState, action) {
switch (action.type) {
case 'MESSAGE_RECEIVED_FROM_RAILS':
return { ...state, messages: [...state.messages, action.payload] };
case 'RAILS_SEND_MESSAGE':
// This action will be intercepted by CableCar and sent to Rails
console.log('Dispatching RAILS_SEND_MESSAGE, CableCar will forward this:', action.payload);
return state;
default:
return state;
}
}
// Step 1: Create cablecar route and middleware
const cableCarRoute = createCableCarRoute();
const cableCarMiddleware = cableCarRoute.createMiddleware();
// Step 2: Add middleware to the Redux store
// Using configureStore from Redux Toolkit for modern setup
const store = configureStore({
reducer: reducer,
middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(cableCarMiddleware),
devTools: process.env.NODE_ENV !== 'production' // Enable Redux DevTools
});
// Step 3: Initialize the cablecar connection to the Redux store and a Rails ActionCable channel
const options = {
// Parameters sent to the Rails channel when subscribing (e.g., params[:room])
params: { room: 'chat_room_1' },
// Define which Redux actions should be sent to the Rails server.
// By default, it matches actions with type prefix 'RAILS_'.
permittedActions: ['RAILS_SEND_MESSAGE', /^CLIENT_TO_SERVER_/],
// ActionCable Callbacks
initialized: () => console.log('CableCar initialized.'),
connected: () => console.log('CableCar connected to MainChannel!'),
disconnected: () => console.log('CableCar disconnected.'),
rejected: () => console.error('CableCar connection rejected.')
};
const cableCar = cableCarRoute.connect(store, 'MainChannel', options);
// Example of dispatching an action that will be sent to the server
store.dispatch({ type: 'RAILS_SEND_MESSAGE', payload: { text: 'Hello from Redux!', author: 'Client' } });
// Example of an action that will NOT be sent to the server (unless explicitly permitted)
store.dispatch({ type: 'LOCAL_ACTION', payload: 'This stays client-side.' });
console.log('Redux store and CableCar middleware initialized. Check console for dispatches.');
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'createMiddleware')
Attempting to call `createMiddleware()` directly on the imported `createCableCarRoute` without first invoking `createCableCarRoute` as a function to get an instance.
fixEnsure `createCableCarRoute` is called as a function to get the route instance: `const cableCarRoute = createCableCarRoute();` then call `cableCarRoute.createMiddleware()`.
Action did not reach Rails server as expected.
The Redux action type dispatched from the client does not match any of the patterns defined in the `permittedActions` configuration for the CableCar connection.
fixVerify that the `type` property of the dispatched Redux action adheres to the `permittedActions` specified in `cableCarRoute.connect()`. Remember the default is a `RAILS_` prefix if `permittedActions` is not explicitly set.
WebSocket connection failed during CableCar initialization.
The ActionCable server URL is incorrect or unreachable, the channel name is misspelled, or the Rails server-side channel is not properly defined or subscribed.
fixCheck the `webSocketURL` option in `createCableCarRoute()` if a custom URL is used (otherwise, it defaults to the host). Ensure the `channel` name passed to `cableCarRoute.connect()` exactly matches your Rails ActionCable channel name (e.g., 'MainChannel'). Verify your Rails channel `subscribed` method is correctly implemented and the server is running.
Audit
Dependencies
reduxrequiredRequired as a Redux store is passed to connect and it's middleware; it is a peer dependency.
@reduxjs/toolkitoptionalOften used alongside Redux for modern Redux development and listed as a peer dependency. Provides `configureStore` and simplifies `applyMiddleware` setup.