Understanding Analytics in Makerkit

The Analytics system in the Makerkit Prisma stack provides a unified interface for tracking user behavior across your SaaS application. Built on a provider-agnostic architecture, it allows you to integrate any analytics service without being locked into a specific vendor.

How Analytics Works

The analytics system is implemented in the @kit/analytics package with two core components:

1. AnalyticsService Interface - The contract all analytics providers must implement
2. AnalyticsManager - Orchestrates multiple providers and broadcasts events to all of them

By default, Makerkit ships with no analytics providers enabled. This is intentional - you choose which analytics service fits your needs and implement a provider for it.

When to Add Analytics

• Use analytics when you need to understand user behavior, track conversions, or measure feature adoption
• Avoid when you're in early development or don't have a clear question you're trying to answer with data
• If unsure start with the NullAnalyticsService (default) and add a real provider once you've reached product-market fit

The AnalyticsService Interface

Every analytics provider implements this interface:

export interface AnalyticsService {
  // Called when the provider is registered
  initialize(): Promise<unknown>;
  // Associate a user with their actions
  identify(userId: string, traits?: Record<string, string>): Promise<unknown>;
  // Track page navigation
  trackPageView(path: string): Promise<unknown>;
  // Track custom events
  trackEvent(
    eventName: string,
    eventProperties?: Record<string, string | string[]>
  ): Promise<unknown>;
}

The interface is straightforward:

• initialize - Set up the analytics SDK, load scripts, etc.
• identify - Associate a user ID with subsequent events
• trackPageView - Record when users navigate between pages
• trackEvent - Record custom events with optional properties

Default Setup

Out of the box, Makerkit uses a NullAnalyticsService that does nothing. This prevents errors when analytics methods are called before you've configured a provider.

import { createAnalyticsManager } from './analytics-manager';
import { NullAnalyticsService } from './null-analytics-service';
import type { AnalyticsManager } from './types';
export const analytics: AnalyticsManager = createAnalyticsManager({
  providers: {
    null: () => NullAnalyticsService,
  },
});

The NullAnalyticsService simply ignores all calls, making it safe to use analytics throughout your codebase without defensive checks.

Using Analytics

Import and use the analytics service anywhere in your application:

import { analytics } from '@kit/analytics';
// Identify a user after sign-in
void analytics.identify('user_123', { plan: 'pro' });
// Track a custom event
void analytics.trackEvent('feature_used', {
  featureName: 'export',
  format: 'csv',
});
// Track a page view (usually handled automatically)
void analytics.trackPageView('/dashboard');

The void keyword is used because these methods return Promises but we don't need to await them in fire-and-forget scenarios.

Multi-Provider Support

The AnalyticsManager can run multiple providers simultaneously. When you call any analytics method, it broadcasts to all registered providers:

export const analytics = createAnalyticsManager({
  providers: {
    googleAnalytics: () => new GoogleAnalyticsService(),
    mixpanel: () => new MixpanelService(),
    posthog: () => new PostHogService(),
  },
});
// This event is sent to all three providers
void analytics.trackEvent('button_clicked', { buttonId: 'signup' });

This lets you use different services for their strengths: Google Analytics for marketing attribution, Mixpanel for product analytics, and PostHog for session replay.

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                   Your Application                   │
│                                                      │
│  ┌─────────────┐                                    │
│  │  Component  │ ──────────▶ analytics.trackEvent() │
│  └─────────────┘                    │               │
│                                     ▼               │
│                          AnalyticsManager           │
│                         /     │      \              │
│                        ▼      ▼       ▼             │
│                  Provider Provider Provider         │
│                    (you implement these)            │
└─────────────────────────────────────────────────────┘

Next Steps

1. Create a custom provider - Implement your preferred analytics service
2. Server-side analytics - Track events from API routes and server actions

Related Documentation

• Environment Variables - Configure analytics API keys
• Deployment - Enable analytics in production
• Monitoring - Error tracking alongside analytics

Next: Creating a Custom Analytics Provider →