Configuring PostHog Monitoring in Your Next.js Supabase SaaS Kit

PostHog combines product analytics, session replay, feature flags, and error tracking in one platform. If you're already using PostHog for analytics, adding it as your monitoring provider lets you correlate errors with user behavior without switching between tools.

Installing the PostHog Plugin

PostHog is distributed as a Makerkit plugin. Install it using the CLI:

npx @makerkit/cli@latest plugins install

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

Registering the Monitoring Service

Register PostHog in the monitoring package by updating three files:

1. Add PostHog to the provider enum

const MONITORING_PROVIDERS = [
  'sentry',
  'posthog', // Add posthog here
  '',
] as const;
export const MONITORING_PROVIDER = z
  .enum(MONITORING_PROVIDERS)
  .optional()
  .transform((value) => value || undefined);

2. Register the server monitoring service

// Register the 'posthog' monitoring service
serverMonitoringRegistry.register('posthog', async () => {
  const { PostHogServerMonitoringService } = await import(
    '@kit/posthog/monitoring/server'
  );
  return new PostHogServerMonitoringService();
});

3. Register the client provider

// Register the PostHog provider
monitoringProviderRegistry.register('posthog', async () => {
  const { PostHogProvider } = await import('@kit/posthog/provider');
  return {
    default: function PostHogProviderWrapper({
      children,
    }: React.PropsWithChildren) {
      return <PostHogProvider>{children}</PostHogProvider>;
    },
  };
});

Environment Variables

Set the monitoring provider and PostHog configuration:

# Enable PostHog as the monitoring provider
NEXT_PUBLIC_MONITORING_PROVIDER=posthog
# PostHog configuration (same as analytics setup)
NEXT_PUBLIC_POSTHOG_KEY=phc_your_key_here
NEXT_PUBLIC_POSTHOG_HOST=https://eu.posthog.com

If you haven't configured PostHog yet, see the PostHog Analytics guide for details on:

• Finding your API key
• Choosing your region (EU vs US)
• Setting up ingestion rewrites to bypass ad blockers

How PostHog Monitoring Works

When PostHog is your monitoring provider, errors are captured and sent to PostHog's error tracking system:

Exception capture

PostHog captures:

• Client-side React errors
• Unhandled promise rejections
• Server-side exceptions via the Next.js instrumentation hook

Errors appear in PostHog under Error Tracking in the sidebar.

Session correlation

The main benefit of using PostHog for monitoring is that errors are automatically linked to session replays. When you view an error in PostHog, you can:

1. See the exact session where the error occurred
2. Watch the user's actions leading up to the error
3. Correlate errors with feature flag states
4. See the user's full journey through your app

This is particularly useful for debugging errors that only happen in specific user flows or under certain conditions.

User identification

When a user signs in, Makerkit identifies them in PostHog. This links errors to specific users, so you can:

• See all errors for a specific user
• Contact users affected by critical bugs
• Filter errors by user properties (plan, account type, etc.)

Limitations

PostHog's error tracking is newer than dedicated tools like Sentry. Consider these limitations:

When to choose PostHog for monitoring:

• You're already using PostHog for analytics
• You want errors correlated with session replays
• Your error volume is moderate
• You prefer fewer tools to manage

When to choose Sentry instead:

• You need detailed stack traces with source maps
• You have high error volume
• You need advanced alerting and issue management
• You want dedicated performance monitoring

Using Both PostHog and Sentry

You can use PostHog for analytics and Sentry for monitoring. Set NEXT_PUBLIC_MONITORING_PROVIDER=sentry while keeping PostHog configured for analytics. This gives you:

• PostHog: Analytics, session replay, feature flags
• Sentry: Error tracking, performance monitoring, source maps

Verification

After setup:

1. Trigger a test error in your application
2. Open PostHog and navigate to Error Tracking
3. Verify the error appears with:
   • Error message and stack trace
   • User information (if logged in)
   • Link to session replay

Troubleshooting

Errors not appearing in PostHog

1. Check the provider setting: Verify NEXT_PUBLIC_MONITORING_PROVIDER=posthog
2. Check PostHog initialization: Open browser DevTools and look for PostHog network requests
3. Verify the registrations: Ensure all three files are updated with PostHog registrations
4. Check ad blockers: If using PostHog directly (no ingestion rewrites), ad blockers may block requests

Session replay not showing for errors

1. Enable session replay: Check PostHog Project Settings > Session Replay
2. Check sample rate: Session replay may be sampling out some sessions
3. Wait for processing: Session replays can take a few minutes to appear

Next Steps

• Learn about PostHog's error tracking features
• Configure session replay settings
• Return to monitoring overview