Analytics

StarterApp includes PostHog analytics integration for user behavior tracking, custom events, and product insights. The integration activates through environment configuration and provides type-safe event tracking.

Configuration

Enable analytics with environment variables:

# PostHog project API key
NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_key

# PostHog API host (cloud or self-hosted)
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

The application detects these variables and initializes PostHog through Next.js instrumentation. CSP configuration in both applications already permits PostHog domains (https://*.posthog.com in connect-src and script-src).

Initialization

PostHog initializes through client-side instrumentation:

import posthog from "posthog-js";
import { publicEnv } from "@workspace/env/client";

if (publicEnv.NEXT_PUBLIC_POSTHOG_KEY && publicEnv.NEXT_PUBLIC_POSTHOG_HOST) {
  posthog.init(publicEnv.NEXT_PUBLIC_POSTHOG_KEY, {
    api_host: publicEnv.NEXT_PUBLIC_POSTHOG_HOST,
    person_profiles: "identified_only",
    capture_pageview: true,
    capture_pageleave: true,
  });
}

The person_profiles: "identified_only" setting respects privacy by tracking anonymous users without creating profiles until authentication occurs.

Automatic Page View Tracking

PostHog captures page views automatically when capture_pageview: true. Navigation events track without manual instrumentation in components.

The integration works across both applications:

• Marketing app: Tracks public page visits
• Dashboard app: Tracks authenticated user navigation

Custom Event Tracking

Track user actions with type-safe events:

Session Recording

Enable session replay for debugging:

posthog.init(key, {
  api_host: host,
  capture_pageview: true,
  session_recording: {
    maskAllInputs: true, // Privacy protection
    maskTextSelector: ".sensitive",
  },
});

Integration Patterns

Common analytics integration points:

Privacy Configuration

PostHog provides privacy controls:

Testing

Test analytics integration without sending events:

import { vi } from "vitest";

// Mock PostHog in tests
vi.mock("posthog-js", () => ({
  default: {
    init: vi.fn(),
    capture: vi.fn(),
    identify: vi.fn(),
    isFeatureEnabled: vi.fn(() => false),
  },
}));

test("tracks checkout event", async () => {
  await handleCheckout("premium");

  expect(posthog.capture).toHaveBeenCalledWith("subscription_started", {
    product_id: "premium",
    monthly_value: 25,
  });
});

Common Events

Standard events for SaaS applications:

Next Steps

Additional Resources