Vue Hotjar Next Plugin

Common errors

• TypeError: app.use is not a function

  cause Attempting to use `vue-hotjar-next` with a Vue 2 application, where the `app` instance and `use` method signature differ.
  fix Ensure your project is running Vue 3. If you need Hotjar for Vue 2, use the `vue-hotjar` package instead.

• Property '$hj' does not exist on type 'ComponentPublicInstance'

  cause When using TypeScript, the global properties `$hj` and `$hjSettings` are added dynamically and might not be automatically inferred on `this` or the component instance without proper type augmentation.
  fix Add a declaration file (e.g., `vue-hotjar-next.d.ts`) to augment the `ComponentCustomProperties` interface with `$hj: HotjarPlugin;` and `$hjSettings: HotjarSettings;`.

• Hotjar tracking data is not appearing in my Hotjar account

  cause Multiple possible causes: `isProduction` is set to `false`, Hotjar ID is incorrect, or the snippet isn't loading due to network issues/ad blockers.
  fix Verify `isProduction` is `true` in your configuration, double-check your Hotjar Site ID, and inspect your browser's network tab to confirm the Hotjar script (`static.hotjar.com/c-v.js`) is loaded without errors.

Warnings

• breaking This plugin is exclusively for Vue 3. It will not work with Vue 2 applications. Attempting to use it with Vue 2 will result in errors related to `app.use` or global property access.
  Fix: For Vue 2 projects, use the `vue-hotjar` package. For Vue 3, ensure your project's Vue version is 3.x.x.
• breaking Version 2.0.0 introduced a major refactor, changing how the Hotjar API and settings are accessed. Previously, users might have interacted directly with `window.hj` or `window._hjSettings`. Now, these are bound to Vue global properties.
  Fix: Migrate your Hotjar API calls from `window.hj` to `app.config.globalProperties.$hj` (or `this.$hj` in components). Similarly, access settings via `app.config.globalProperties.$hjSettings`.
• gotcha The `isProduction` parameter, which controls whether Hotjar tracking is enabled, defaults to `true` if not explicitly defined. This means tracking might be active in development environments unless explicitly set to `false`.
  Fix: Always explicitly configure `isProduction`, typically by binding it to your Node environment variable, e.g., `isProduction: process.env.NODE_ENV === 'production'`.
• gotcha The `id` parameter, representing your Hotjar Site ID, supports both `number` and `string` types. Before v2.1.0, while it might have worked, the type definition primarily suggested a number. Version 2.1.0 explicitly added string ID support and refined validation.
  Fix: If using a string ID, ensure you are on `vue-hotjar-next` version 2.1.0 or later to guarantee full compatibility and correct validation.

Install

• npm install vue-hotjar-next npm
• yarn add vue-hotjar-next yarn
• pnpm add vue-hotjar-next pnpm

Imports

• VueHotjar
  wrong:

  import { VueHotjar } from 'vue-hotjar-next';

  correct:

  import VueHotjar from 'vue-hotjar-next';

  The plugin is exported as a default export.
• $hj
  wrong:

  window.hj

  correct:

  app.config.globalProperties.$hj

  Access Hotjar's Identify API via Vue's global property instead of the global window object. For components, use `this.$hj` (Options API) or `getCurrentInstance().appContext.config.globalProperties.$hj` (Composition API).
• $hjSettings
  wrong:

  window._hjSettings

  correct:

  app.config.globalProperties.$hjSettings

  Access Hotjar's settings (ID, snippet version) via Vue's global property.

Quickstart

This quickstart demonstrates how to install and initialize the `vue-hotjar-next` plugin in a Vue 3 application, including configuration for the Hotjar ID, production environment, and snippet version. It also hints at how to access the `$hj` global property for Hotjar's Identify API.

import { createApp } from 'vue';
import App from './App.vue';
import VueHotjar from 'vue-hotjar-next';

const app = createApp(App);

app.use(VueHotjar, {
  id: process.env.VUE_APP_HOTJAR_ID ?? 12345678,
  isProduction: process.env.NODE_ENV === 'production',
  snippetVersion: 6
});

app.mount("#app");

// Example of accessing Hotjar Identify API globally or in a component (after setup)
// In a component (Options API):
// export default {
//   mounted() {
//     this.$hj('identify', 'USER_ID', { userProperty: 'value' });
//   }
// };

// In a component (Composition API):
// import { getCurrentInstance } from 'vue';
// const instance = getCurrentInstance();
// instance.appContext.config.globalProperties.$hj('identify', 'USER_ID', { userProperty: 'value' });