Registry / observability / vue-hotjar-next

vue-hotjar-next

library2.1.0jsnpmunverified

Vue Hotjar Next is a plugin designed for integrating Hotjar analytics seamlessly into Vue 3 applications. Currently stable at version 2.1.0, the package follows an as-needed release cadence, with significant updates like the v2.0.0 major refactor improving API access and type safety. Key differentiators include its exclusive compatibility with Vue 3 (requiring `vue-hotjar` for Vue 2 projects), providing direct access to the Hotjar Identify API and configuration settings via Vue's global properties (`$hj` and `$hjSettings`). This approach allows developers to interact with Hotjar functions like `hj('identify', ...)` through `$hj` without directly manipulating the `window.hj` object, offering a more Vue-idiomatic integration. It also ships with TypeScript types, ensuring robust development.

observability communication

npm install vue-hotjar-next

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-HOTJAR-NEXT

vue-hotjar-next

observabilityjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueHotjar

✓ import VueHotjar from 'vue-hotjar-next';

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

The plugin is exported as a default export.

$hj

✓ app.config.globalProperties.$hj

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

✓ app.config.globalProperties.$hjSettings

✗ window._hjSettings

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

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' });

Debug

Known issues

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

affects: >=2.0.0

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

affects: >=2.0.0

gotchaThe `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'`.

affects: >=1.0.0

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

affects: <2.1.0

Errors

Common errors & fixes

TypeError: app.use is not a function

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'

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

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.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

vuerequiredRequired as a peer dependency for `app.use()` and global properties.

Agent activity

33 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/henk-badenhorst/vue-hotjar-next ↗

packagehttps://www.npmjs.com/package/vue-hotjar-next ↗