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://zerostarter.dev/docs/manage/analytics)
NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
NEXT_PUBLIC_POSTHOG_KEY=

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, following Next.js's client instrumentation convention (this file runs once, early, on the client before the app hydrates):

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 shared posthog client is then handed to React through PostHogProvider in web/next/src/app/providers.tsx. That file exports an OuterProvider (PostHog wrapping TanStack Query, with the dev tools rendered outside production) and an InnerProvider (next-themes plus the Sonner Toaster):

"use client"

import { isProduction } from "@packages/env"
import { env } from "@packages/env/web-next"
import { PostHogProvider } from "@posthog/react"
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import posthog from "posthog-js"
import { useState } from "react"

import { DevTools } from "@/components/devtools"

export function OuterProvider({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient())

  return (
    <PostHogProvider client={posthog}>
      <QueryClientProvider client={queryClient}>
        {children}
        {!isProduction(env.NEXT_PUBLIC_NODE_ENV) && <DevTools />}
      </QueryClientProvider>
    </PostHogProvider>
  )
}

Usage

The snippets below are generic PostHog SDK guidance for instrumenting your own product.

The starter wires up PostHog initialization and the React provider for you, but it does not call capture, identify, or read feature flags anywhere by default. Add those where they make sense in your code.

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