{"id":10478,"library":"actioncable-vue","title":"ActionCable-Vue Plugin","description":"actioncable-vue is a Vue plugin designed to simplify the integration of ActionCable, Ruby on Rails' WebSocket framework, into Vue.js applications. It provides a straightforward API for managing WebSocket connections, subscribing to channels, and handling real-time data. Currently at stable version 3.1.2, the package appears to have an active development cadence, indicated by recent commits and continuous maintenance. A key differentiator is its support for both Vue 2 and Vue 3, allowing developers to use the same plugin across different generations of Vue projects, adapting its API usage accordingly. It abstracts away much of the boilerplate associated with direct ActionCable consumer usage, offering options for debugging, connection URL configuration (including dynamic URLs for JWTs), immediate connection, and automatic unsubscription upon component unmount.","status":"active","version":"3.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/mclintprojects/actioncable-vue","tags":["javascript","actioncable","vue","vuejs","vue3","rails","real-time","websocket","typescript"],"install":[{"cmd":"npm install actioncable-vue","lang":"bash","label":"npm"},{"cmd":"yarn add actioncable-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add actioncable-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for the plugin to integrate with Vue.js applications (supports Vue 2 and Vue 3).","package":"vue","optional":false},{"reason":"Runtime dependency, provides the underlying ActionCable client for WebSocket communication with a Rails backend.","package":"actioncable","optional":false}],"imports":[{"note":"This is the default export used for plugin installation via `app.use()` in Vue 3 or `Vue.use()` in Vue 2.","wrong":"import { ActionCableVue } from 'actioncable-vue'","symbol":"ActionCableVue","correct":"import ActionCableVue from 'actioncable-vue'"},{"note":"Introduced for Vue 3 Composition API usage to access the cable instance and subscription methods (`subscribe`, `unsubscribe`).","symbol":"useCable","correct":"import { useCable } from 'actioncable-vue'"},{"note":"Available on the Vue instance (e.g., in Options API components) after the plugin is installed. It exposes methods like `connection` and `subscriptions`.","symbol":"Vue instance property ($cable)","correct":"this.$cable"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport App from './App.vue';\nimport ActionCableVue from 'actioncable-vue';\n\nconst actionCableVueOptions = {\n debug: true,\n debugLevel: 'info',\n // Example: Connect to a local ActionCable server. In production, this would be your backend URL.\n // Use process.env for sensitive or environment-specific URLs.\n connectionUrl: process.env.VUE_APP_ACTION_CABLE_URL ?? 'ws://localhost:3000/cable',\n connectImmediately: true,\n unsubscribeOnUnmount: true,\n // Optional: If you use Vuex or Pinia, you can pass your store here for easier access within channels.\n // store: myVuexStore\n};\n\ncreateApp(App)\n .use(ActionCableVue, actionCableVueOptions)\n .mount('#app');\n\n// Example component usage with Composition API\n// ","lang":"typescript","description":"Demonstrates how to install `actioncable-vue` as a Vue 3 plugin and configure its connection options. It includes a commented-out example of how to use `useCable` in a Composition API component to subscribe to a channel and handle messages."},"warnings":[{"fix":"For Vue 3, update your `main.js` or `main.ts` to use `createApp().use(ActionCableVue, options)`. For Vue 2, continue using `Vue.use(ActionCableVue, options)`.","message":"The installation method changed significantly between Vue 2 and Vue 3. Vue 2 uses `Vue.use(ActionCableVue, options)`, while Vue 3 requires `createApp(App).use(ActionCableVue, options)`. Direct `new Vue()` instantiation is no longer applicable for global plugin registration in Vue 3.","severity":"breaking","affected_versions":">=3.0"},{"fix":"Always explicitly set the `connectionUrl` option to your ActionCable server's WebSocket endpoint, especially in production or when your frontend and backend are on different domains. Example: `connectionUrl: 'ws://your-api-domain.com/cable'`.","message":"If `connectionUrl` is not explicitly provided during plugin installation, `actioncable-vue` will defer to ActionCable's default behavior, which typically attempts to connect to `/cable` on the same host. This might not be suitable for API-only backends or cross-origin setups.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"If your ActionCable server requires dynamic authentication (e.g., JWT in query params), configure `connectionUrl` as a function: `connectionUrl: () => `ws://localhost:3000/cable?token=${yourAuthToken}`.","message":"The `connectionUrl` option can be a function that returns the URL. This is critical for dynamic authentication schemes, such as appending JWTs to the WebSocket URL. Failing to use a function for dynamic tokens will result in expired or missing authentication.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Ensure `connectImmediately` aligns with your application's needs. If `false`, manually trigger connection using `this.$cable.connection.connect()` or ensure a subscription is initiated to establish the connection. Keep `unsubscribeOnUnmount` as `true` unless you have a specific reason to maintain subscriptions after component destruction.","message":"By default, `connectImmediately` is `true` and `unsubscribeOnUnmount` is `true`. While `unsubscribeOnUnmount` helps prevent memory leaks and unnecessary subscriptions, setting `connectImmediately` to `false` without manually calling `this.$cable.connection.connect()` or subscribing to a channel will delay the WebSocket connection indefinitely.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `createApp(App).use(ActionCableVue, options)` is called before mounting your Vue 3 application, or `Vue.use(ActionCableVue, options)` for Vue 2. Verify that `$cable` is accessed within a component's lifecycle hook or method.","cause":"The ActionCableVue plugin was not correctly installed on the Vue instance/application, or `this.$cable` is being accessed outside a Vue component's context where `this` refers to the component instance. This often happens if `app.use()` is missed or incorrectly placed.","error":"TypeError: Cannot read properties of undefined (reading '$cable')"},{"fix":"Double-check that your Rails ActionCable server is running and configured correctly. Verify the `connectionUrl` in your `actioncable-vue` options matches the actual WebSocket endpoint of your backend. Ensure no firewalls or proxies are blocking the connection.","cause":"The `connectionUrl` provided to `actioncable-vue` is incorrect, or the ActionCable server is not running, not accessible at the specified URL, or not configured to handle WebSocket connections at the `/cable` endpoint.","error":"WebSocket connection to 'ws://localhost:3000/cable' failed: Error during WebSocket handshake: Unexpected response code: 404"},{"fix":"Ensure `@rails/actioncable` (if directly used) or `actioncable` (as a dependency of `actioncable-vue`) is correctly installed and compatible with your build setup. Update `actioncable-vue` and `actioncable` to their latest versions. You might need to adjust your build tool's configuration (e.g., Vite's `optimizeDeps` or `alias`) if the issue persists.","cause":"This typically indicates an issue with a build tool (like Vite) resolving the `actioncable` dependency, possibly due to incorrect package.json entries or an older version of `actioncable` that doesn't properly expose ESM exports.","error":"Error: [plugin: vite:dep-scan] Failed to resolve entry for package \"@rails/actioncable\". The package may have incorrect main/module/exports specified in its package.json."}],"ecosystem":"npm"}