Vue.js integration for Laravel Echo

Common errors

• TypeError: Cannot read properties of undefined (reading 'private') at VueComponent.mounted

  cause The `vue-echo` plugin or `laravel-echo` instance was not properly initialized or registered with Vue.
  fix Ensure `Vue.use(VueEcho, { broadcaster: 'pusher', key: '...' });` is called before creating your root Vue instance, and that all necessary `laravel-echo` dependencies (like `pusher-js` or `socket.io-client`) are installed and configured correctly.

• TypeError: this.$echo is undefined

  cause The `vue-echo` plugin has not been registered with Vue, or the component is being accessed before the plugin has fully initialized.
  fix Verify that `Vue.use(VueEcho, ...)` is invoked correctly and that `vue-echo` and `laravel-echo` are installed (`npm install vue-echo laravel-echo pusher-js`). For server-side rendering (SSR), ensure `this.$echo` access is guarded against non-browser environments.

• Webpack compilation error: Cannot find module 'vue-echo'

  cause The `vue-echo` package is not installed as a project dependency.
  fix Run `npm install vue-echo laravel-echo --save` or `yarn add vue-echo laravel-echo` to add the package to your project.

Warnings

• breaking Version 1.0.0 introduced `vm` as a second parameter to locally registered event callbacks (i.e., callbacks defined in the `echo` option of a Vue component). This was added to provide direct access to the Vue instance, improving context handling. Code written for versions prior to 1.0.0 where `this` was used within these callbacks might need adjustment if `this` was expected to refer to the Vue instance.
  Fix: Update event handlers in the `echo` component option to accept `(payload, vm)` and use `vm` instead of `this` for accessing the Vue instance context.
• gotcha This library is designed for Vue 2. It will not work with Vue 3 due to fundamental changes in Vue's plugin system and reactivity model. Attempting to use `vue-echo` in a Vue 3 project will result in errors.
  Fix: For Vue 3 projects, you must find an alternative solution or integrate Laravel Echo manually via a custom plugin or composable. This package is not compatible with Vue 3.
• gotcha When defining event listeners within the `echo` option of a Vue component, the `this` context inside the callback does not directly refer to the Vue instance by default (prior to v1.0.0, or if not using the `vm` parameter in v1.0.0+).
  Fix: Since v1.0.0, event callbacks receive the Vue instance as a second parameter (`(payload, vm) => { vm.someData = payload; }`). Always use this `vm` parameter to safely access component data and methods. For manual listeners via `this.$echo.listen()`, arrow functions `() => {}` are recommended to retain the lexical `this` context of the `mounted` hook or method where they are defined.
• gotcha The `channel` option on a Vue instance (`this.channel`) only references the instance's specifically subscribed channel when using the declarative `channel` option. For other channels, use the global `this.$echo` instance.
  Fix: Understand that `this.channel` is a convenience for the single channel defined in the component's `channel` option. For dynamic subscriptions or managing multiple channels, always use the `this.$echo` instance (e.g., `this.$echo.channel('another-channel')`).

Install

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

Imports

• VueEcho
  wrong:

  import { VueEcho } from 'vue-echo';

  correct:

  import VueEcho from 'vue-echo';

  VueEcho is the default export for the plugin. It is passed to `Vue.use()` for plugin registration.
• $echo

  this.$echo.private('channel').listen('Event', callback);

  The Laravel Echo instance is automatically injected into all Vue instances as `this.$echo` after plugin registration.
• channel/echo component options

  new Vue({
    channel: 'my-channel',
    echo: { 'MyEvent': (payload, vm) => { /* ... */ } }
  });

  For declarative, component-level subscriptions, define `channel` and `echo` options directly on your Vue instance or component.

Quickstart

This quickstart demonstrates how to initialize `vue-echo` with Laravel Echo configuration (Pusher example), and then how to subscribe to public and private channels using both the `this.$echo` instance and the declarative `channel` and `echo` component options.

import Vue from 'vue';
import VueEcho from 'vue-echo';
import Echo from 'laravel-echo'; // Assuming laravel-echo is installed

// Option 1: Initialize VueEcho directly with configuration
Vue.use(VueEcho, {
    broadcaster: 'pusher',
    key: 'YOUR_PUSHER_APP_KEY', // Replace with your Pusher App Key or environment variable
    cluster: 'mt1', // Optional, replace with your cluster
    forceTLS: true // Optional
});

// Option 2: Pass an existing Laravel Echo instance
/*
const echoInstance = new Echo({
    broadcaster: 'pusher',
    key: 'YOUR_PUSHER_APP_KEY',
    cluster: 'mt1',
    forceTLS: true
});
Vue.use(VueEcho, echoInstance);
*/

const app = new Vue({
    el: '#app',
    data: {
        messages: []
    },
    // Declarative channel subscription within the component
    channel: 'public.chat',
    echo: {
        'ChatMessageSent': (payload, vm) => {
            console.log('New message received via declarative config:', payload.message);
            vm.messages.push(payload.message);
        }
    },
    mounted() {
        console.log('VueEcho instance available:', this.$echo);
        // Manual subscription via this.$echo
        this.$echo.private('private.notifications.user.1')
            .listen('NewNotification', (notification) => {
                console.log('New private notification:', notification);
            });
        
        // Manually listen on the component's channel if defined
        if (this.channel) {
            this.channel.listen('AnotherEvent', (payload) => {
                console.log('Another event on component channel:', payload);
            });
        }
    },
    template: `
        <div>
            <h1>Vue-Echo Example</h1>
            <p>Check console for real-time events.</p>
            <h2>Public Chat Messages:</h2>
            <ul>
                <li v-for="(msg, index) in messages" :key="index">{{ msg }}</li>
            </ul>
        </div>
    `
});