Custom Analytics Provider

The analytics package in this repo is an abstraction layer. It does not ship provider implementations for GA4, PostHog, Umami, or other vendors.

What Exists

• @kit/analytics
• @kit/analytics/server
• AnalyticsService
• createAnalyticsManager()
• NullAnalyticsService

The default client and server exports both register only the null provider:

• packages/analytics/src/index.ts
• packages/analytics/src/server.ts

Provider Contract

Implement AnalyticsService from packages/analytics/src/types.ts:

export interface AnalyticsService {
  initialize(): Promise<unknown>;
  trackEvent(
    eventName: string,
    eventProperties?: Record<string, string | string[]>,
  ): Promise<unknown>;
  trackPageView(path: string): Promise<unknown>;
  identify(
    userId: string,
    traits?: Record<string, string>,
  ): Promise<unknown>;
}

Registration Pattern

Register your provider with createAnalyticsManager():

import { createAnalyticsManager } from '@kit/analytics';
import { MyAnalyticsService } from './my-analytics-service';
export const analytics = createAnalyticsManager({
  providers: {
    myAnalytics: () => new MyAnalyticsService(),
  },
});

Use the same approach for @kit/analytics/server if your provider has a separate server SDK.

App Wiring

The app publishes events from apps/web/components/analytics-provider.tsx. That component maps app events into:

• analytics.trackEvent(...)
• analytics.trackPageView(...)
• analytics.identify(...)

If you replace the default analytics export with your own manager, that app wiring can stay unchanged.