@northslopetech/analytics

Provider-agnostic analytics, error tracking, and web vitals for OSDK React apps. Currently backed by PostHog, but application code programs against abstract interfaces — swap the provider without changing a line of product code.

Install

pnpm add @northslopetech/analytics

Peer dependencies: react >=18, react-dom >=18.

Quick start

1. Set environment variables

VITE_POSTHOG_KEY=phc_...
VITE_POSTHOG_HOST=https://us.i.posthog.com   # optional, defaults to US cloud

2. Initialize at the app root

import {
  createAnalyticsClient,
  createErrorTrackingClient,
  trackWebVitals,
  AnalyticsProvider,
  ErrorBoundary,
} from "@northslopetech/analytics";

const analyticsClient = createAnalyticsClient({
  appName: "my-app",
  appVersion: "1.0.0",
  environment: "production",
});

const errorTrackingClient = createErrorTrackingClient();
errorTrackingClient?.startAutoCapture();

if (analyticsClient) {
  trackWebVitals(analyticsClient);
}

function App() {
  return (
    <ErrorBoundary errorTrackingClient={errorTrackingClient}>
      {analyticsClient ? (
        <AnalyticsProvider client={analyticsClient}>
          <MyApp />
        </AnalyticsProvider>
      ) : (
        <MyApp />
      )}
    </ErrorBoundary>
  );
}

3. Track events from components

import { useAnalytics } from "@northslopetech/analytics";

function SearchBar() {
  const analytics = useAnalytics();

  function onSearch(query: string) {
    analytics.trackSearch(query);
  }

  return <input onChange={(e) => onSearch(e.target.value)} />;
}

useAnalytics() returns a no-op client when called outside an AnalyticsProvider, so it's safe to use unconditionally.

API

Factory functions

| Function | Returns | Description | | --- | --- | --- | | createAnalyticsClient(config) | AnalyticsClient \| null | Reads VITE_POSTHOG_KEY / VITE_POSTHOG_HOST and returns an initialized client, or null if unconfigured. | | createErrorTrackingClient() | ErrorTrackingClient \| null | Same env-var detection; returns an error tracking client or null. |

AnalyticsClient

interface AnalyticsClient {
  init(config?: Record<string, unknown>): void;
  identify(distinctId: string, properties?: Record<string, unknown>): void;
  track(eventName: string, properties?: Record<string, unknown>): void;
  trackPageView(pageName?: string, properties?: Record<string, unknown>): void;
  setUserProperties(properties: Record<string, unknown>): void;
  setUserPropertiesOnce(properties: Record<string, unknown>): void;
  registerSuperProperties(properties: Record<string, unknown>): void;
  registerSessionProperties(properties: Record<string, unknown>): void;
  unregisterSuperProperty(propertyName: string): void;
  trackLinkClick(url: string, properties?: Record<string, unknown>): void;
  trackSearch(query: string, properties?: Record<string, unknown>): void;
  reset(): void;
  getDistinctId(): string | undefined;
}

ErrorTrackingClient

interface ErrorTrackingClient {
  captureError(error: unknown, additionalProperties?: Record<string, unknown>): void;
  startAutoCapture(): void;
}

React components & hooks

| Export | Description | | --- | --- | | <AnalyticsProvider client={...}> | Provides the analytics client via React context. | | useAnalytics() | Returns the context client, or a silent no-op fallback. | | <ErrorBoundary> | Catches render errors, reports them via ErrorTrackingClient, and shows a fallback UI. Accepts an optional fallback prop. | | trackWebVitals(client) | Subscribes to LCP, CLS, INP, FCP, and TTFB and reports each metric through the analytics client. |

Concrete implementations

| Class | Implements | | --- | --- | | PostHogAnalyticsClient | AnalyticsClient — wraps posthog-js. | | NoOpAnalyticsClient | AnalyticsClient — silent no-op, useful for tests or disabled environments. | | PostHogErrorTrackingClient | ErrorTrackingClient — wraps PostHog exception capture. | | NoOpErrorTrackingClient | ErrorTrackingClient — silent no-op. |

Development

pnpm install
pnpm build        # produces ESM + CJS in dist/
pnpm test         # runs vitest