Use Vue Components in Angular 1.x

Common errors

• Uncaught ReferenceError: process is not defined

  cause ngVue versions prior to 1.7.5 attempted to access the Node.js `process` global in browser environments, leading to errors.
  fix Upgrade `ngVue` to version 1.7.5 or later. If using an older version and a bundler, ensure `process` is properly polyfilled or mocked for browser builds.

• Uncaught TypeError: e.warn is not a function

  cause This error occurred in `ngVue` versions prior to 1.7.4 when the internal logger attempted to call a `warn` method on an object that did not have it defined.
  fix Upgrade `ngVue` to version 1.7.4 or later to fix the logger initialization logic.

Warnings

• breaking ngVue is specifically designed for Vue 2 and AngularJS 1.x. For applications targeting Vue 3, users *must* switch to the separate `ngVue3` package, as `ngVue` is not compatible with Vue 3.
  Fix: If migrating to Vue 3, install `@jaredmcateer/ngvue3` and refactor component integration accordingly. Do not attempt to use `ngVue` with Vue 3.
• breaking Earlier versions of ngVue (2.0.0 to 2.1.0) had incomplete or broken ESM (ECMAScript Module) support, which could lead to build failures or runtime errors when bundling with modern tools. This was primarily due to incorrect `exports` field in `package.json`.
  Fix: Upgrade to `ngVue@2.2.0` or later for significantly improved and more robust ESM compatibility. If stuck on an older version, consider using CommonJS imports or a bundler configuration that specifically handles legacy module formats.
• gotcha Version 2.0.0 introduced support for Vue 2 Composition API. While described as having no *expected* breaking changes, this was a significant internal refactor. Existing components or integrations might exhibit subtle behavioral differences or require minor adjustments if they relied on specific internal behaviors of `ngVue` before this update.
  Fix: Thoroughly test applications when upgrading from `ngVue` versions prior to 2.0.0, especially those using complex component interactions or the Vue 2 Composition API features.
• gotcha Versions of `ngVue` prior to 1.7.8 had a known memory leak issue related to the mounted lifecycle hook of Vue components, which could cause performance degradation in long-running Angular 1.x applications with a high turnover of Vue components.
  Fix: Upgrade `ngVue` to version 1.7.8 or later to resolve the memory leak issue.
• deprecated Before version 2.2.1, a deprecation warning related to camelCase event naming styles could appear during bootstrapping. Although the specific warning was removed, it's generally best practice to use kebab-case for custom events in Vue components exposed through `ngVue` to ensure consistency and avoid potential issues with HTML attribute parsing.
  Fix: Ensure all custom events emitted by Vue components integrated with `ngVue` are defined and emitted using kebab-case (e.g., `my-event`) rather than camelCase (e.g., `myEvent`).

Install

• npm install ngVue npm
• yarn add ngVue yarn
• pnpm add ngVue pnpm

Imports

• ngVue (module registration)
  wrong:

  const ngVue = require('ngVue');
  angular.module('yourApp', [ngVue]);

  correct:

  import 'ngVue';
  angular.module('yourApp', ['ngVue']);

  The `ngVue` package exports itself as an Angular module that registers globally when imported/required. The Angular application then depends on the string literal `'ngVue'`.
• createVueComponent
  wrong:

  import createVueComponent from 'ngVue';

  correct:

  import { createVueComponent } from 'ngVue';

  This factory is a named export, typically injected into Angular services or controllers to programmatically convert Vue component definitions into Angular-compatible directives.
• ngVueReduxPlugin (example)
  wrong:

  import { ngVueReduxPlugin } from 'ngVue/plugins/redux';

  correct:

  import 'ngVue/plugins/redux';
  angular.module('yourApp', ['ngVue', 'ngVueReduxPlugin']);

  Specific plugins, like the Redux integration, often register themselves as separate Angular modules and are imported for their side-effects, making their module name available for Angular dependency.

Quickstart

Demonstrates how to integrate a Vue 2 component into an AngularJS 1.x application using `ngVue`, passing props and handling events.

import angular from 'angular';
import Vue from 'vue';
import 'ngVue';

// Define a simple Vue component
const MyGreetingComponent = {
  template: `
    <div>
      <h3>Hello from Vue!</h3>
      <p>{{ message }}</p>
      <button @click="emitEvent">Click me (Vue)</button>
    </div>
  `,
  props: ['message'],
  methods: {
    emitEvent() {
      this.$emit('vue-clicked', 'Hello from Vue event!');
    }
  }
};

// Register ngVue and define the Angular app
angular.module('myApp', ['ngVue'])
  .controller('MyController', function($scope, $rootScope, createVueComponent) {
    // Expose the Vue component to ngVue via $rootScope.components
    // This is a common pattern for ngVue to find components by name
    $rootScope.components = {
      MyGreetingComponent: MyGreetingComponent
    };

    $scope.angularMessage = 'Data from Angular scope.';
    $scope.vueData = {
      message: 'This prop is passed from Angular to Vue.'
    };
    $scope.vueEvents = {
      'vue-clicked': function(payload) {
        console.log('Vue component clicked! Payload:', payload);
        alert('Vue component received event: ' + payload);
      }
    };
  });

// To use in HTML (assuming an index.html file):
// <div ng-app="myApp" ng-controller="MyController">
//   <h2>Angular App with Vue Component</h2>
//   <p>Message from Angular: {{ angularMessage }}</p>
//   <vue-component name="MyGreetingComponent" v-props="vueData" v-on="vueEvents"></vue-component>
// </div>