Analytics

Overview

ZeroStarter includes built-in integration with PostHog for comprehensive product analytics, feature flags, session recordings, and user behavior tracking. When configured, PostHog automatically tracks page views and user interactions.

Features

Product Analytics: Track user behavior and product usage
Session Recordings: Replay user sessions for debugging and insights
Feature Flags: Roll out features gradually with confidence
A/B Testing: Run experiments to optimize your product
Funnels & Paths: Understand user journeys and conversion flows

Setup

1. Create a PostHog Account

Sign up at PostHog (cloud) or self-host
Create a new project
Copy your Project API Key from Project Settings

2. Configure Environment Variables

Add your PostHog credentials to your .env file:

# Optional: PostHog Analytics (https://eu.posthog.com)
NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_api_key

Note: Use https://us.i.posthog.com for US Cloud, https://eu.i.posthog.com for EU Cloud, or your self-hosted URL.

3. Environment Configuration

The PostHog variables are configured in packages/env/src/web-next.ts:

client: {
  NEXT_PUBLIC_POSTHOG_HOST: z.url().optional(),
  NEXT_PUBLIC_POSTHOG_KEY: z.string().optional(),
}

Implementation

PostHog is initialized in web/next/instrumentation-client.ts:

import { env } from "@packages/env/web-next"
import posthog from "posthog-js"

if (typeof window !== "undefined" && env.NEXT_PUBLIC_POSTHOG_KEY) {
  posthog.init(env.NEXT_PUBLIC_POSTHOG_KEY, {
    api_host: env.NEXT_PUBLIC_POSTHOG_HOST || "https://eu.i.posthog.com",
    defaults: "2025-11-30",
  })
}

The PostHog provider wraps the application in web/next/src/app/providers.tsx:

import { PostHogProvider } from "@posthog/react"
import posthog from "posthog-js"

export function OuterProvider({ children }: { children: React.ReactNode }) {
  return (
    <PostHogProvider client={posthog}>
      {children}
    </PostHogProvider>
  )
}

Usage

Track Custom Events

import posthog from "posthog-js"

// Track a custom event
posthog.capture("button_clicked", {
  button_name: "signup",
  page: "landing",
})

Identify Users

import posthog from "posthog-js"

// Identify a user after authentication
posthog.identify(user.id, {
  email: user.email,
  name: user.name,
})

Feature Flags

import posthog from "posthog-js"

// Check if a feature flag is enabled
if (posthog.isFeatureEnabled("new-dashboard")) {
  // Show new dashboard
}

React Hooks

import { usePostHog, useFeatureFlagEnabled } from "@posthog/react"

function Component() {
  const posthog = usePostHog()
  const showNewFeature = useFeatureFlagEnabled("new-feature")

  const handleClick = () => {
    posthog?.capture("feature_used")
  }

  return showNewFeature ? <NewFeature onClick={handleClick} /> : <OldFeature />
}

Disabling Analytics

To disable PostHog analytics, simply remove or leave empty the NEXT_PUBLIC_POSTHOG_KEY environment variable. PostHog will not initialize if the key is not provided.

Privacy Considerations

PostHog supports privacy-first analytics with configurable data retention
Session recordings can be disabled or configured to mask sensitive data
GDPR-compliant with data residency options (EU/US)
Users can opt-out using PostHog's built-in opt-out mechanisms