3. If using Webpack or another bundler, mirror those aliases:

{
  "resolve": {
    "alias": {
      "@src": path.resolve(__dirname, "src/clarity-js"),
      "@clarity-types": path.resolve(__dirname, "node_modules/clarity/types")
    }
  }
}

4. Install the upstream package to obtain shared type declarations:

npm install user@example.com

5. The library runs in a browser context. It accesses window, document, navigator, performance, and MutationObserver. Do not import it in Node.js server-side code paths; gate it behind an typeof window !== "undefined" check.

6. No environment variables are required by the core library. Configuration is passed via the config() call (see Public API).

Public API

clarity (namespace)

import { clarity } from "./src/clarity-js/index";

clarity.start(config?: Config): void
clarity.stop(): void
clarity.pause(): void
clarity.resume(): void
clarity.upgrade(key: string): void
clarity.version: string

The clarity namespace is the primary lifecycle handle. Call clarity.start() once the DOM is ready to begin capturing. Call clarity.stop() to end a session cleanly. upgrade signals an intent to escalate capture fidelity for the current session.

helper

import { helper } from "./src/clarity-js/index";

helper.hash(value: string): string
helper.selector.getSelector(node: Node): string
helper.get(id: number): Node
helper.getNode(node: Node): number
helper.lookup(node: Node): number

helper bundles utilities for DOM introspection and hashing. Use helper.hash to produce the same deterministic hash that clarity uses internally for node fingerprinting. Use helper.selector.* to resolve CSS selectors for arbitrary DOM nodes in the same way clarity does.

core.config (function)

import { config } from "./src/clarity-js/core/index";

config(override: Config): boolean

Apply configuration overrides before calling start(). Returns false if the session is already active or override is null. Accepts any subset of keys defined in Config (@clarity-types/core): upload URL, project ID, masking rules, sampling rate, etc.

core.check (function)

import { check } from "./src/clarity-js/core/index";

check(): boolean

Returns true if the current browser environment satisfies all prerequisites (Promise, MutationObserver, TreeWalker, Date.now, performance.now, WeakMap) and Global Privacy Control is not set. Use this guard before calling start() to avoid errors in unsupported environments.

Working examples

Scenario - Basic page instrumentation

Initialize clarity as early as possible in your page bundle. Guard against unsupported browsers and Global Privacy Control before starting.

import { clarity, version } from "./src/clarity-js/index";
import { check, config } from "./src/clarity-js/core/index";

if (check()) {
  config({
    projectId: "your-project-id",
    upload: "https://your-collector-endpoint.example.com/clarity",
    lean: false,
  });
  clarity.start();
  console.log("Clarity started, version:", version);
}

Scenario - Hashing a CSS selector for a known node

Use helper to replicate clarity's internal hashing logic when you need stable identifiers for DOM nodes in your own analytics pipeline.

import { helper } from "./src/clarity-js/index";

function getNodeFingerprint(node: Element): string {
  const sel = helper.selector.getSelector(node);
  const hash = helper.hash(sel);
  return hash;
}

const button = document.querySelector("#submit-btn");
if (button) {
  const id = getNodeFingerprint(button);
  console.log("Stable node ID:", id);
}

Scenario - Stopping and restarting clarity across route changes in a SPA

In single-page applications, stop the session on route change and restart to capture page views as independent sessions.

import { clarity } from "./src/clarity-js/index";
import { check, config } from "./src/clarity-js/core/index";

function onRouteChange(newPath: string): void {
  clarity.stop();

  if (check()) {
    config({
      projectId: "your-project-id",
      upload: "https://your-collector-endpoint.example.com/clarity",
    });
    clarity.start();
    console.log("New clarity session started for:", newPath);
  }
}

window.addEventListener("popstate", () => onRouteChange(location.pathname));

File walkthrough

• clarity.ts - Orchestrates module start/stop order; exposes the public lifecycle API.
• index.ts - Re-exports clarity, version, and helper; the package entry point.
• global.ts - Holds mutable global references shared across modules (window handle, document reference, etc.).
• queue.ts - Manages the internal async event queue and controls flush timing.
• core/api.ts - Internal API surface shared across core utilities.
• core/config.ts - Default configuration object and runtime overrides.
• core/copy.ts - Deep-copy utility for safe state snapshots.
• core/dynamic.ts - Handles dynamic module loading.
• core/event.ts - Event registry and dispatch within the core pipeline.
• core/hash.ts - Deterministic string hashing used for node and selector fingerprinting.
• core/history.ts - URL and navigation history tracking.
• core/index.ts - Core module lifecycle (start, stop, active, check, config).
• core/measure.ts - Performance measurement wrappers for internal profiling.
• core/report.ts - Internal error/diagnostic reporting.
• core/scrub.ts - PII scrubbing helpers.
• core/task.ts - Cooperative task scheduler using idle callbacks.
• core/throttle.ts - Rate-limiting utility.
• core/time.ts - Session-relative timestamp generation.
• core/timeout.ts - Safe setTimeout wrappers.
• core/version.ts - Exposes the library version string.
• data/ - Full data pipeline: envelope framing, upload, compression, consent, cookies, metrics, variables, dimensions, signals, pings, and summaries.
• diagnostic/ - Fraud heuristics, script error capture, and internal telemetry.
• dynamic/agent/ - Auto-detects and integrates with LiveChat, Tidio, and Crisp agents at startup.
• insight/ - Page snapshot and blank-state encoding.
• interaction/ - All user interaction event handlers (click, scroll, pointer, input, clipboard, resize, etc.).
• layout/ - DOM mutation observation, virtual node tree, and CSS selector generation.
• performance/ - Navigation timing and resource performance entries.

Common pitfalls and fixes

• Running in SSR/Node.js context: The library references window and document at module scope. Gate all imports behind typeof window !== "undefined" or lazy-import inside a useEffect / browser entry point.
• @clarity-types path not resolved: The type aliases must be configured in both tsconfig.json and your bundler. Missing one causes silent type errors or runtime crashes; add both alias entries.
• check() returns false due to Global Privacy Control: navigator.globalPrivacyControl === true causes check() to return false by design. Do not call start() in that case; respect the user's preference.
• Calling config() after start(): config() returns false and applies no changes once the session is active. Always call config() before clarity.start().
• Multiple start() calls without stop(): The active() guard in core/index.ts prevents double-start, but event listeners accumulate if stop() is not called first on SPA navigation. Always pair stop() → start().
• TypeScript path alias conflicts: If your project already uses @src for its own code, rename the alias in both tsconfig.json and your bundler config to something like @clarity-src and do a find-replace in the copied source files.

Vibe-coding prompt template

I have copied the clarity-js instrumentation source into `src/clarity-js/` in my project.
The upstream package is `user@example.com`. I also have `USAGE.md` in the same directory.

Please help me integrate clarity-js step by step:

1. Read `USAGE.md` for the full API reference and project setup instructions.
2. Add the required `tsconfig.json` path aliases (`@src` -> `src/clarity-js`, `@clarity-types` -> `node_modules/clarity/types`).
3. Add equivalent aliases to my bundler config (Webpack / Vite / esbuild - ask me which I use).
4. Create an `analytics.ts` bootstrap module that:
   - Imports `clarity`, `version`, and `helper` from `src/clarity-js/index`.
   - Imports `check` and `config` from `src/clarity-js/core/index`.
   - Guards initialization with `check()`.
   - Applies config overrides (projectId, upload endpoint) before calling `clarity.start()`.
   - Exports a `stopClarity` function for SPA route cleanup.
5. Wire the bootstrap module into my application entry point.
6. Show me how to use `helper.hash` and `helper.selector.getSelector` to fingerprint a DOM node.
7. Point out any pitfalls specific to my framework (ask me if it is Next.js, Remix, plain Webpack, etc.).

Use only the exports visible in USAGE.md. Do not invent new APIs.

License and credit

The upstream project is released under the MIT License (see source/LICENSE if present, or verify at the clarity GitHub repository). This block is derived from user@example.com published by Microsoft. Original project: https://github.com/microsoft/clarity.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.