ActionCable-Vue Plugin

Common errors

• TypeError: Cannot read properties of undefined (reading '$cable')

  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.
  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.

• WebSocket connection to 'ws://localhost:3000/cable' failed: Error during WebSocket handshake: Unexpected response code: 404

  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.
  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.

• 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.

  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.
  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.

Warnings

• breaking 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.
  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)`.
• gotcha 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.
  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'`.
• gotcha 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.
  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}`.
• gotcha 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.
  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.

Install

• npm install actioncable-vue npm
• yarn add actioncable-vue yarn
• pnpm add actioncable-vue pnpm

Imports

• ActionCableVue
  wrong:

  import { ActionCableVue } from 'actioncable-vue'

  correct:

  import ActionCableVue from 'actioncable-vue'

  This is the default export used for plugin installation via `app.use()` in Vue 3 or `Vue.use()` in Vue 2.
• useCable

  import { useCable } from 'actioncable-vue'

  Introduced for Vue 3 Composition API usage to access the cable instance and subscription methods (`subscribe`, `unsubscribe`).
• Vue instance property ($cable)

  this.$cable

  Available on the Vue instance (e.g., in Options API components) after the plugin is installed. It exposes methods like `connection` and `subscriptions`.

Quickstart

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.

import { createApp } from 'vue';
import App from './App.vue';
import ActionCableVue from 'actioncable-vue';

const actionCableVueOptions = {
  debug: true,
  debugLevel: 'info',
  // Example: Connect to a local ActionCable server. In production, this would be your backend URL.
  // Use process.env for sensitive or environment-specific URLs.
  connectionUrl: process.env.VUE_APP_ACTION_CABLE_URL ?? 'ws://localhost:3000/cable',
  connectImmediately: true,
  unsubscribeOnUnmount: true,
  // Optional: If you use Vuex or Pinia, you can pass your store here for easier access within channels.
  // store: myVuexStore
};

createApp(App)
  .use(ActionCableVue, actionCableVueOptions)
  .mount('#app');

// Example component usage with Composition API
// <script setup>
// import { useCable, onMounted, onUnmounted, ref } from 'actioncable-vue';
// const { subscribe, unsubscribe, cable } = useCable();
// const message = ref('');
// let chatSubscription;

// onMounted(() => {
//   chatSubscription = subscribe(
//     { channel: 'ChatChannel', room: 'general' },
//     {
//       received(data) {
//         message.value = data.message; // Assuming data has a 'message' field
//         console.log('Received:', data);
//       },
//       connected() {
//         console.log('Connected to ChatChannel');
//       },
//       disconnected() {
//         console.log('Disconnected from ChatChannel');
//       }
//     }
//   );
// });

// onUnmounted(() => {
//   if (chatSubscription) {
//     unsubscribe(chatSubscription);
//   }
// });
// </script>