Easy Event Handling for Vue 1 & 2

Common errors

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

  cause The `vue-events` plugin was not correctly installed via `Vue.use(VueEvents)` before creating Vue instances, or the import path for `VueEvents` was incorrect.
  fix Ensure `import VueEvents from 'vue-events'; Vue.use(VueEvents);` is executed *before* any Vue instances that attempt to use `$events` are created. Verify the import path is correct.

• Property '$events' does not exist on type 'Vue'.

  cause Using TypeScript without proper type declaration merging for the `vue-events` plugin, or the plugin was not installed globally onto the Vue prototype.
  fix Ensure the plugin is installed with `Vue.use(VueEvents)`. If using TypeScript, you might need to add a declaration file to augment the `Vue` instance type, typically by declaring a module `vue-events` and adding `$events` to `Vue.prototype`.

• This plugin cannot be installed because it has already been installed.

  cause Attempting to call `Vue.use(VueEvents)` multiple times in the application lifecycle.
  fix `Vue.use()` should typically be called only once at the application's entry point (e.g., `main.ts` or `main.js`). Remove redundant calls to `Vue.use(VueEvents)`.

Warnings

• breaking This package is fundamentally incompatible with Vue 3.x. Vue 3 removed the `$on`, `$off`, and `$once` instance methods from Vue instances, which `vue-events` relies upon for its global event bus functionality. Attempting to use `vue-events` in a Vue 3 application will result in runtime errors.
  Fix: For Vue 3, consider using alternative event emitter libraries like `mitt` or `tiny-emitter`, or adopt more idiomatic Vue 3 communication patterns such as props/emits, provide/inject, or global state management with Pinia/Vuex.
• deprecated The global event bus pattern, while convenient for simple cases, is largely discouraged in modern Vue 2.x and especially Vue 3.x applications. It can lead to hard-to-trace event flows, hidden dependencies, and maintainability issues as applications grow.
  Fix: Prefer explicit component communication via props and `$emit` for parent-child, `provide`/`inject` for descendant communication, or dedicated state management solutions like Vuex/Pinia for global state.
• gotcha The package provides multiple aliases for its core methods (`fire`, `emit`, `$emit` for emitting; `listen`, `on`, `$on` for listening; `remove`, `off`, `$off` for removing). While intended for flexibility, this can lead to inconsistent code styles within a team and confusion about which alias to use.
  Fix: Establish a team convention for which aliases to consistently use, e.g., sticking to the Vue-native `$emit`, `$on`, `$off` names.

Install

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

Imports

• VueEvents
  wrong:

  const VueEvents = require('vue-events')

  correct:

  import VueEvents from 'vue-events'

  This plugin is typically installed using `Vue.use(VueEvents)`. The `require()` pattern is for older CommonJS environments or when Vue is globally available (e.g., via `window.Vue`).
• Vue
  wrong:

  import { Vue } from 'vue'

  correct:

  import Vue from 'vue'

  Required to install the plugin via `Vue.use()`. Vue's default export is the constructor.
• $events
  wrong:

  this.$emit('myEvent', payload) (when intending to use the global bus)

  correct:

  this.$events.fire('myEvent', payload)

  `$events` is added to the Vue prototype after plugin installation; it's not directly imported. It acts as the global event bus.

Quickstart

This quickstart demonstrates how to install `vue-events` and use its `$events.on` and `$events.fire` methods to communicate between parts of a Vue 2.x application.

import Vue from 'vue';
import VueEvents from 'vue-events';

// Install the plugin
Vue.use(VueEvents);

// Create a root Vue instance
new Vue({
  el: '#app',
  data() {
    return {
      message: 'Hello from Vue Events!'
    };
  },
  mounted() {
    // Listen for an event
    this.$events.on('exampleEvent', (data) => {
      console.log('Received exampleEvent:', data);
      this.message = `Event received: ${data.detail}`;
    });

    // Fire an event after a short delay
    setTimeout(() => {
      this.$events.fire('exampleEvent', { detail: 'Data from emitter!' });
    }, 1000);
  },
  beforeDestroy() {
    // It's good practice to remove listeners to prevent memory leaks
    this.$events.off('exampleEvent');
  },
  template: `
    <div>
      <h1>Vue Events Demo</h1>
      <p>{{ message }}</p>
      <button @click="triggerAnotherEvent">Trigger Another Event</button>
    </div>
  `,
  methods: {
    triggerAnotherEvent() {
      this.$events.emit('anotherEvent', { source: 'button' });
    }
  }
});

// A separate component or instance can also listen or emit
new Vue({
  mounted() {
    this.$events.listen('anotherEvent', (data) => {
      console.log('Another event caught!', data);
    });
  }
}).$mount(document.createElement('div')); // Mount without an element to just make it active.