Using the PostHog Analytics Provider in Tanstack Start Supabase Turbo

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
• 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:

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:

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:

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

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:

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

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:

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.

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

Next Steps

• Learn about Analytics and Events for custom event tracking
• Set up PostHog for monitoring
• Try Umami for simpler, privacy-focused analytics