@vllnt/analytics

Lightweight, privacy-first analytics library with consent management and React integration.

Features

• Event tracking with pre-init queuing (no lost events during hydration)
• Consent management — two categories (analytics + functional), localStorage + SSR cookie
• Versioned consent — bump version to re-prompt users
• Do Not Track — respects browser DNT setting
• SSR-safe — all browser APIs guarded
• Zero external analytics dependencies — bring your own backend (Vercel Analytics, GA, custom)

Install

pnpm add @vllnt/analytics

Peer dependency: react ^18.0.0 || ^19.0.0

Ships ESM and CommonJS builds with type declarations; no bundler transpilation of node_modules is needed.

Usage

React Provider

import { AnalyticsProvider } from "@vllnt/analytics/react";

function App() {
  return (
    <AnalyticsProvider config={{ app: "my-app", version: 1, debug: true }}>
      {children}
    </AnalyticsProvider>
  );
}

Consent Banner

import { useConsent } from "@vllnt/analytics/react";

function CookieBanner() {
  const { hasResponded, isLoading, acceptAll, declineAnalytics } = useConsent();

  if (isLoading || hasResponded) return null;

  return (
    <div>
      <p>We use cookies for analytics.</p>
      <button onClick={acceptAll}>Accept</button>
      <button onClick={declineAnalytics}>Decline</button>
    </div>
  );
}

Track Events

import { track, trackPage } from "@vllnt/analytics";

// Generic event
track("button_click", { id: "cta-hero" });

// Page view
trackPage({ path: "/about" });

Tutorial Tracking

Typed helpers for tutorial/content flows:

import {
  trackTutorialStart,
  trackSectionView,
  trackSectionComplete,
  trackTutorialComplete,
  trackTutorialNavigation,
  trackTimeSpent,
} from "@vllnt/analytics";

trackTutorialStart({
  tutorial_id: "getting-started",
  tutorial_title: "Getting Started",
  locale: "en",
  total_sections: 5,
});

trackSectionView({
  tutorial_id: "getting-started",
  tutorial_title: "Getting Started",
  locale: "en",
  section_id: "intro",
  section_index: 0,
  total_sections: 5,
});

Identify Users

import { identify, resetAnalytics } from "@vllnt/analytics";

// After login
identify("user-123", { plan: "pro" });

// After logout
resetAnalytics();

Consent Utilities (non-React)

import {
  loadConsent,
  saveConsent,
  clearConsent,
  createAcceptAllConsent,
  createDeclineAnalyticsConsent,
  getConsentFromCookie,
  isDoNotTrackEnabled,
  needsRePrompt,
} from "@vllnt/analytics";

// SSR: read consent from cookie header
const analyticsAllowed = getConsentFromCookie(request.headers.cookie);

// Check if re-prompt needed after version bump
const consent = loadConsent();
if (consent && needsRePrompt(consent, 2)) {
  clearConsent();
}

API

Core

Function	Description
initAnalytics(config)	Initialize analytics singleton
track(name, properties?)	Track a custom event (empty names are ignored)
trackPage(properties?)	Track a page view
identify(userId, traits?)	Identify a user (empty ids are ignored)
resetAnalytics()	Clear user identity (logout)
enableAnalytics(config)	Re-enable after consent granted
disableAnalytics()	Disable after consent revoked
isAnalyticsEnabled()	Check if tracking is active

Consent

Function	Description
loadConsent()	Load consent from localStorage
saveConsent(state)	Persist consent to localStorage + cookie
clearConsent()	Remove consent (triggers re-prompt)
createAcceptAllConsent()	Create accept-all consent state
createDeclineAnalyticsConsent()	Create analytics-declined state
updateConsentCategory(state, category, value)	Update a single category
needsRePrompt(consent, version)	Check if version requires re-prompt
getConsentFromCookie(cookieString)	Parse consent from cookie (SSR)
isDoNotTrackEnabled()	Check browser DNT setting

React (@vllnt/analytics/react)

Export	Description
AnalyticsProvider	Context provider — wires consent + analytics init
useAnalytics()	Access full analytics context
useConsent(options?)	Standalone consent hook for banner UIs

How It Works

User visits site
  │
  ├─ DNT enabled? ──▶ Block all tracking
  │
  ├─ Consent exists?
  │    ├─ Version outdated? ──▶ Clear & re-prompt
  │    ├─ Analytics declined? ──▶ Block tracking
  │    └─ Analytics accepted ──▶ Initialize & flush queue
  │
  └─ No consent ──▶ Queue events until user responds

Events fired before initialization are queued and flushed once consent is granted and analytics initializes.

Scripts

pnpm test          # Run tests (watch mode)
pnpm test:once     # Run tests once
pnpm test:coverage # Run with coverage
pnpm lint          # Lint
pnpm lint:fix      # Lint + autofix
pnpm typecheck     # Type-check
pnpm build         # Build dist (ESM, CJS, types)

License

MIT