{"id":12495,"library":"vue-hotjar-next","title":"Vue Hotjar Next Plugin","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/henk-badenhorst/vue-hotjar-next","tags":["javascript","vue3","plugin","hotjar","analytics","typescript"],"install":[{"cmd":"npm install vue-hotjar-next","lang":"bash","label":"npm"},{"cmd":"yarn add vue-hotjar-next","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-hotjar-next","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for `app.use()` and global properties.","package":"vue","optional":false}],"imports":[{"note":"The plugin is exported as a default export.","wrong":"import { VueHotjar } from 'vue-hotjar-next';","symbol":"VueHotjar","correct":"import VueHotjar from 'vue-hotjar-next';"},{"note":"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).","wrong":"window.hj","symbol":"$hj","correct":"app.config.globalProperties.$hj"},{"note":"Access Hotjar's settings (ID, snippet version) via Vue's global property.","wrong":"window._hjSettings","symbol":"$hjSettings","correct":"app.config.globalProperties.$hjSettings"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport App from './App.vue';\nimport VueHotjar from 'vue-hotjar-next';\n\nconst app = createApp(App);\n\napp.use(VueHotjar, {\n  id: process.env.VUE_APP_HOTJAR_ID ?? 12345678,\n  isProduction: process.env.NODE_ENV === 'production',\n  snippetVersion: 6\n});\n\napp.mount(\"#app\");\n\n// Example of accessing Hotjar Identify API globally or in a component (after setup)\n// In a component (Options API):\n// export default {\n//   mounted() {\n//     this.$hj('identify', 'USER_ID', { userProperty: 'value' });\n//   }\n// };\n\n// In a component (Composition API):\n// import { getCurrentInstance } from 'vue';\n// const instance = getCurrentInstance();\n// instance.appContext.config.globalProperties.$hj('identify', 'USER_ID', { userProperty: 'value' });","lang":"typescript","description":"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."},"warnings":[{"fix":"For Vue 2 projects, use the `vue-hotjar` package. For Vue 3, ensure your project's Vue version is 3.x.x.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always explicitly configure `isProduction`, typically by binding it to your Node environment variable, e.g., `isProduction: process.env.NODE_ENV === 'production'`.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project is running Vue 3. If you need Hotjar for Vue 2, use the `vue-hotjar` package instead.","cause":"Attempting to use `vue-hotjar-next` with a Vue 2 application, where the `app` instance and `use` method signature differ.","error":"TypeError: app.use is not a function"},{"fix":"Add a declaration file (e.g., `vue-hotjar-next.d.ts`) to augment the `ComponentCustomProperties` interface with `$hj: HotjarPlugin;` and `$hjSettings: HotjarSettings;`.","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.","error":"Property '$hj' does not exist on type 'ComponentPublicInstance'"},{"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.","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.","error":"Hotjar tracking data is not appearing in my Hotjar account"}],"ecosystem":"npm"}