heatmap

heatmap is a worker-first activity tracking package for web apps. It captures cursor movement, clicks, and scroll behavior with both absolute and screen-relative coordinates, and provides a separate CLI to generate heatmap reports.

What this package gives you

• Browser tracker (createActivityTracker) with Web Worker processing by default.
• Event payloads with:
  • Absolute coordinates (clientX, clientY, pageX, pageY, screenX, screenY)
  • Relative coordinates normalized to viewport/page (0..1)
• Batched output so you can store data in your own DB.
• Toggleable overlay renderer (createHeatmapOverlay) with blue -> green -> red intensity.
• CLI command (activity-heatmap generate) to produce standalone HTML heatmap reports from exported JSON.

Install

npm install heatmap

Browser tracking (worker-backed)

import { createActivityTracker } from "heatmap";

const tracker = createActivityTracker({
  enabled: true,
  useWorker: true,
  sampleIntervalMs: 50,
  flushIntervalMs: 1000,
  batchSize: 200,
  onBatch: (batch) => {
    // Optional local hook
    console.log("activity batch", batch.sequence, batch.events.length);
  },
  transport: async (batch) => {
    // Store in your backend / DB
    await fetch("/api/activity", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(batch),
    });
  },
});

tracker.start();

// Later:
// tracker.flush();
// tracker.stop();

Toggle overlay (for selected envs)

import { createHeatmapOverlay } from "heatmap";

if (import.meta.env.MODE !== "production") {
  const overlay = createHeatmapOverlay({
    enabled: false,
    toggleKey: "h",
  });

  // Feed aggregated data from API / exported state
  overlay.updateFromBatches(batchesFromServer);

  // Optional explicit control:
  // overlay.show();
  // overlay.hide();
}

CLI report generation

Generate a standalone HTML heatmap report from exported JSON.

activity-heatmap generate \
  --input ./exports/activity.json \
  --output ./reports/heatmap.html \
  --title "Checkout Flow Heatmap"

Input supports:

• ActivityBatch[]
• HeatCellAggregate[]
• { batches: ActivityBatch[] }
• { aggregates: HeatCellAggregate[] }
• NDJSON (one JSON object per line)

Build

npm run build

License

MIT