@hitkeep/tracker

@hitkeep/tracker

Typed, cookieless web analytics tracking for React, Vue, Angular, Astro, and any other bundler-based frontend — a privacy-friendly Google Analytics alternative that stores no cookies and needs no consent banner for basic measurement.

This is the official browser SDK for HitKeep, a self-hostable, GDPR-friendly analytics platform that runs as a single Go binary. The package bundles the same tracker that ships as HitKeep's hk.js snippet — compiled from the same source — as a fully typed ES module.

• Cookieless by default — no cookies, no cross-site identifiers, no consent banner for basic analytics
• Framework-native — no <script> tag, no window.hk casts, full TypeScript types
• Automatic tracking — pageviews, SPA route changes, outbound links, file downloads, form submits
• Typed e-commerce events — view_item, add_to_cart, begin_checkout, purchase
• Tiny and self-contained — ~3.7 kB gzipped, zero runtime dependencies, ESM + CJS

Install

npm install @hitkeep/tracker

Quick start

import { init, track } from '@hitkeep/tracker';

init({ host: 'https://your-hitkeep.example.com' });

track('signup_clicked', { plan: 'pro' });

host is the origin (or path prefix) your HitKeep instance serves the tracker from — the same URL the hk.js snippet would load from, including custom tracking domains. Pageviews are captured automatically, including history-based SPA navigations, so no router wiring is required.

Framework examples

React and Next.js

'use client';

import { useEffect } from 'react';
import { cleanup, init } from '@hitkeep/tracker';

export function Analytics() {
    useEffect(() => {
        init({ host: 'https://your-hitkeep.example.com' });
        return cleanup;
    }, []);

    return null;
}

Vue and Nuxt

import { createApp } from 'vue';
import { init } from '@hitkeep/tracker';
import App from './App.vue';

init({ host: 'https://your-hitkeep.example.com' });

createApp(App).mount('#app');

Angular

import { ApplicationConfig, provideAppInitializer } from '@angular/core';
import { init } from '@hitkeep/tracker';

export const appConfig: ApplicationConfig = {
    providers: [provideAppInitializer(() => init({ host: 'https://your-hitkeep.example.com' }))]
};

Astro

<script>
    import { init } from '@hitkeep/tracker';

    init({ host: 'https://your-hitkeep.example.com' });
</script>

Full walkthroughs for each framework, including Next.js App Router and Astro view transitions, are in the npm package guide.

API

Configuration

init({
    host: 'https://your-hitkeep.example.com', // required
    autoCapturePageviews: true, // send a pageview on init
    autoTrackSpaNavigation: true, // pageviews on pushState/replaceState/popstate
    outboundLinks: true, // outbound_click events
    fileDownloads: true, // file_download events
    formSubmissions: true, // form_submit events
    webVitals: false, // load the Web Vitals bundle from `${host}/hk-vitals.js`
    useBeacon: true, // prefer navigator.sendBeacon
    respectDoNotTrack: true, // drop tracking when DNT is enabled
    captureOnLocalhost: false, // localhost is blocked by default
    bindToWindow: true // expose window.hk.event for snippet-compatible callers
});

Each option maps to a hk.js data attribute where one exists — see the tracker architecture guide for the delivery, retry, and storage behavior shared by both.

E-commerce

import { trackPurchase } from '@hitkeep/tracker';

trackPurchase({
    transaction_id: 'tx-1042',
    value: 49.9,
    currency: 'EUR',
    items: [{ item_id: 'sku-1', item_name: 'Starter Plan', quantity: 1, price: 49.9 }]
});

Visitor opt-out

This package bundles the tracker into your application, so content blockers do not filter it. Offer visitors an explicit opt-out:

import { blockTrackingForMe, enableTrackingForMe, isTrackingEnabled } from '@hitkeep/tracker';

The opt-out persists in localStorage under hk_ignore and is honored by both this package and the hk.js snippet.

What you need to run it

The package sends data to a HitKeep instance. You can self-host HitKeep as a single binary, Docker image, or Helm chart, or use HitKeep Cloud. HitKeep is open source under the MIT license — the source for this package lives in PascaleBeier/hitkeep.

Documentation

• NPM package guide — framework integration, full API reference, differences from the snippet
• Tracker architecture — delivery, retries, SPA handling, storage boundaries
• Custom events — event naming and property conventions
• Automatic events — outbound clicks, downloads, form submits
• E-commerce analytics — purchase funnel tracking
• Self-hosting HitKeep — binary, Docker Compose, Kubernetes

Versioning

This package is versioned in lockstep with HitKeep itself and published with every HitKeep release. Keep the major version aligned with your HitKeep instance.

License

MIT © Pascale Beier — see LICENSE.