vite-plugin-ms-clarity

1.0.0 verified Mon Apr 27 auth: no javascript

Vite plugin for integrating Microsoft Clarity analytics. Current stable version is 1.0.0. This plugin simplifies adding Clarity tracking to any Vite project (compatible with Vite ^4 || ^5). It ships TypeScript types and is lightweight with no additional runtime dependencies. Unlike manual injection, this plugin handles environment variables, script loading, and type-safe options.

Common errors

error Cannot find module 'vite-plugin-ms-clarity' or its corresponding type declarations. ↓

cause Package not installed or type resolution not configured.

fix

Run npm install vite-plugin-ms-clarity --save-dev and ensure tsconfig.json has compilerOptions.types or includes node_modules.

error ViteError: No known conditions for './dist/index.mjs' specifier for 'vite-plugin-ms-clarity' ↓

cause Old Vite version or incorrect module resolution.

fix

Upgrade Vite to ^4 || ^5 and clear node_modules/.vite cache (rm -rf node_modules/.vite).

error Uncaught TypeError: Cannot read properties of undefined (reading 'push') ↓

cause Clarity ID is empty or undefined when plugin is enabled.

fix

Set the environment variable VITE_CLARITY_ID to a valid Clarity project ID.

Warnings

gotcha The plugin does not validate the Clarity ID format. An invalid or empty ID will cause a runtime error in the browser. ↓

fix Ensure the environment variable VITE_CLARITY_ID is set and valid before building.

breaking Only supports Vite ^4 || ^5. Will not work with Vite 3 or earlier. ↓

fix Upgrade Vite to version 4 or 5.

deprecated The Options type may change in future minor versions as stricter validation is added. ↓

fix Review the Options interface after each update and fix any type errors.

Install

npm install vite-plugin-ms-clarity

yarn add vite-plugin-ms-clarity

pnpm add vite-plugin-ms-clarity

Imports

vitePluginMsClarity

wrong

const vitePluginMsClarity = require('vite-plugin-ms-clarity')

correct

import vitePluginMsClarity from 'vite-plugin-ms-clarity'

Package provides a default export. ESM-only; CJS require is not supported.

MsClarityOptions

wrong

import { MsClarityOptions } from 'vite-plugin-ms-clarity'

correct

import type { MsClarityOptions } from 'vite-plugin-ms-clarity'

Type-only import to avoid runtime side effects. MsClarityOptions is not a runtime value.

MsClarityPlugin
wrong
```
import MsClarityPlugin from 'vite-plugin-ms-clarity'
```
correct
```
import { MsClarityPlugin } from 'vite-plugin-ms-clarity'
```
Named export for the plugin class is available, but the default export is the plugin function. Use named import only if you need the class type.

Quickstart

Shows how to integrate the plugin with Vite using environment variable for the Clarity ID.

// vite.config.ts
import { defineConfig } from 'vite';
import vitePluginMsClarity from 'vite-plugin-ms-clarity';

export default defineConfig({
  plugins: [
    vitePluginMsClarity({
      id: process.env.VITE_CLARITY_ID ?? '',
      enable: true
    })
  ]
});