# Using the PostHog Analytics Provider in Tanstack Start Supabase Turbo

> Add PostHog to your MakerKit application for product analytics, session replay, and feature flags with client-side and server-side support.

*Canonical: https://makerkit.dev/docs/tanstack-supabase/analytics/posthog-analytics-provider*

---

PostHog provides product analytics, session replay, feature flags, and A/B testing in one platform. 

Unlike marketing-focused tools, PostHog helps you understand how users interact with your product. 

Posthog supports both client-side and server-side tracking, and can be self-hosted for full data control.

## Prerequisites

Before starting:

- Create a PostHog account at [posthog.com](https://posthog.com)
- Note your Project API Key (starts with `phc_`)
- Choose your region: `eu.posthog.com` or `us.posthog.com`

Find your API key in PostHog: **Project Settings > Project API Key**.

## Installation

Install the PostHog plugin using the MakerKit CLI:

```bash
npx @makerkit/cli@latest plugins add posthog
```

Our codemod will wire up the plugin in your project, so you don't have to do anything manually. Please review the changes with `git diff`.

Add environment variables:

```bash {% title=".env.local" %}
VITE_POSTHOG_KEY=phc_your_key_here
VITE_POSTHOG_HOST=https://eu.posthog.com
```

Use `https://us.posthog.com` if your project is in the US region.

## Server-Side Configuration

PostHog supports server-side analytics for tracking events in server routes and server functions:

Use server-side tracking in your code:

```typescript
import { createServerFn } from '@tanstack/react-start';

import { analytics } from '@kit/analytics/server';

export const createProject = createServerFn({ method: 'POST' })
  .validator(ProjectSchema)
  .handler(async ({ data }) => {
    const project = await db.projects.create(data);

    await analytics.trackEvent('project.created', {
      projectId: project.id,
      userId: data.userId,
    });

    return project;
  });
```

## Bypassing Ad Blockers with Ingestion Rewrites

Ad blockers frequently block PostHog. Use Tanstack Start rewrites to proxy requests through your domain:

### Step 1: Add the Ingestion URL

```bash {% title=".env.local" %}
VITE_POSTHOG_KEY=phc_your_key_here
VITE_POSTHOG_HOST=https://eu.posthog.com
VITE_POSTHOG_INGESTION_URL=http://localhost:3000/ingest
```

In production, replace `localhost:3000` with your domain.

### Step 2: Configure Nitro Route Rules

Tanstack Start is served by Nitro, so proxy the ingestion path with Nitro route rules. Add them to the Nitro options in `apps/web/vite.config.ts`:

```typescript {% title="apps/web/vite.config.ts" %}
import { nitro } from 'nitro/vite';

// ...within your plugins array
nitro({
  config: {
    routeRules: {
      // Change 'eu' to 'us' if using the US region
      '/ingest/static/**': {
        proxy: 'https://eu-assets.i.posthog.com/static/**',
      },
      '/ingest/**': {
        proxy: 'https://eu.i.posthog.com/**',
      },
    },
  },
}),
```

There is no Next.js middleware or `_next` matcher in this kit, so nothing else needs to be excluded — the `/ingest` path is handled directly by the proxy rules above.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `VITE_POSTHOG_KEY` | Yes | Your PostHog Project API Key |
| `VITE_POSTHOG_HOST` | Yes | PostHog host (`https://eu.posthog.com` or `https://us.posthog.com`) |
| `VITE_POSTHOG_INGESTION_URL` | No | Proxy URL to bypass ad blockers (e.g., `https://yourdomain.com/ingest`) |

## Verification

After configuration:

1. Open your application
2. Navigate between pages
3. Open PostHog > Activity > Live Events
4. Confirm page views and events appear

If using ingestion rewrites, check the Network tab for requests to `/ingest` instead of `posthog.com`.

## Using with Other Providers

PostHog works alongside other analytics providers:

```typescript {% title="packages/analytics/src/index.ts" %}
import { createPostHogAnalyticsService } from '@kit/posthog/client';
import { createGoogleAnalyticsService } from '@kit/google-analytics';

import { createAnalyticsManager } from './analytics-manager';

export const analytics = createAnalyticsManager({
  providers: {
    posthog: createPostHogAnalyticsService,
    'google-analytics': createGoogleAnalyticsService,
  },
});
```

## PostHog Features Beyond Analytics

PostHog offers additional features beyond event tracking:

- **Session Replay**: Watch user sessions to debug issues
- **Feature Flags**: Control feature rollouts
- **A/B Testing**: Run experiments on UI variants
- **Surveys**: Collect user feedback

These features are available in the PostHog dashboard once you are capturing events.

For monitoring features (error tracking), see the [PostHog Monitoring guide](/docs/tanstack-supabase/monitoring/posthog).

## Troubleshooting

### Events not appearing

- Verify your API key starts with `phc_`
- Confirm the host matches your project region (EU vs US)
- Check for ad blockers if not using ingestion rewrites

### CORS errors with ingestion rewrites

- Verify the Nitro `routeRules` proxy destination matches your region
- Confirm the `/ingest` path prefix matches your `VITE_POSTHOG_INGESTION_URL`

### Server-side events not appearing

- Ensure you import from `@kit/analytics/server`, not `@kit/analytics`
- Server-side tracking requires the same environment variables

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "Should I use the EU or US region?", "answer": "Use the EU region (eu.posthog.com) if you have European users and want GDPR-compliant data residency. The US region may have slightly lower latency for US-based users."},
     {"question": "Can I self-host PostHog?", "answer": "Yes. PostHog can be self-hosted using Docker. Update VITE_POSTHOG_HOST to your self-hosted instance URL."},
     {"question": "How do I enable session replay?", "answer": "Session replay is enabled by default in PostHog. Configure recording settings in PostHog > Project Settings > Session Replay."},
     {"question": "Do ingestion rewrites work on Vercel?", "answer": "Yes. The Nitro routeRules proxy works on Vercel and other Tanstack Start hosting platforms."},
     {"question": "Is PostHog GDPR compliant?", "answer": "PostHog can be GDPR compliant. Use the EU region for data residency, enable cookie-less tracking, and integrate with a consent management solution."}
   ]
/%}

## Next Steps

- [Learn about Analytics and Events](analytics-and-events) for custom event tracking
- [Set up PostHog for monitoring](/docs/tanstack-supabase/monitoring/posthog)
- [Try Umami](umami-analytics-provider) for simpler, privacy-focused analytics