PostHog Analytics Setup in MakerKit

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. It 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 install

Select PostHog from the list. This creates the plugin at packages/plugins/posthog.

Add the plugin as a dependency to the analytics package:

pnpm add "@kit/posthog@workspace:*" --filter "@kit/analytics" -D

Client-Side Configuration

Register the provider for client-side analytics:

import { createPostHogAnalyticsService } from '@kit/posthog/client';
import { createAnalyticsManager } from './analytics-manager';
import type { AnalyticsManager } from './types';
export const analytics: AnalyticsManager = createAnalyticsManager({
  providers: {
    posthog: createPostHogAnalyticsService,
  },
});

Add environment variables:

NEXT_PUBLIC_POSTHOG_KEY=phc_your_key_here
NEXT_PUBLIC_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 API routes and Server Actions:

import 'server-only';
import { createPostHogAnalyticsService } from '@kit/posthog/server';
import { createAnalyticsManager } from './analytics-manager';
import type { AnalyticsManager } from './types';
export const analytics: AnalyticsManager = createAnalyticsManager({
  providers: {
    posthog: createPostHogAnalyticsService,
  },
});

Use server-side tracking in your code:

import { analytics } from '@kit/analytics/server';
export async function createProject(data: ProjectData) {
  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 Next.js rewrites to proxy requests through your domain:

Step 1: Add the Ingestion URL

NEXT_PUBLIC_POSTHOG_KEY=phc_your_key_here
NEXT_PUBLIC_POSTHOG_HOST=https://eu.posthog.com
NEXT_PUBLIC_POSTHOG_INGESTION_URL=http://localhost:3000/ingest

In production, replace localhost:3000 with your domain.

Step 2: Configure Next.js Rewrites

Add rewrites to your Next.js configuration:

/** @type {import('next').NextConfig} */
const config = {
  // Required for PostHog trailing slash API requests
  skipTrailingSlashRedirect: true,
  async rewrites() {
    // Change 'eu' to 'us' if using the US region
    return [
      {
        source: '/ingest/static/:path*',
        destination: 'https://eu-assets.i.posthog.com/static/:path*',
      },
      {
        source: '/ingest/:path*',
        destination: 'https://eu.i.posthog.com/:path*',
      },
    ];
  },
};
export default config;

Step 3: Exclude from CSRF Protection

Exclude the ingestion endpoint from CSRF middleware:

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|images|locales|assets|ingest/*|api/*).*)',
  ],
};

Note: For versions prior to Next.js 16, use apps/web/middleware.ts instead.

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

• Ensure skipTrailingSlashRedirect: true is set in next.config.mjs
• Verify the rewrite destination matches your region

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