Required Configuration

PostHog API Key

Your PostHog project API key is required to send events to PostHog.

import { HydrateBeerProvider } from 'hydrate-beer/react';

function App() {
  return (
    <HydrateBeerProvider
      config={{
        posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
      }}
    >
      {/* Your app */}
    </HydrateBeerProvider>
  );
}

Always use environment variables for your PostHog API key. Never hardcode it directly in your source code.

Finding Your PostHog API Key

Sign in to your PostHog account
Navigate to Project Settings
Copy your Project API Key from the project details

Optional Configuration

PostHog Host

Specify which PostHog instance you're using. Defaults to PostHog US Cloud.

posthogHost: 'https://us.posthog.com' // US Cloud (default)
posthogHost: 'https://eu.posthog.com' // EU Cloud
posthogHost: 'https://your-instance.com' // Self-hosted

Examples:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    posthogHost: 'https://us.posthog.com', // Optional, this is the default
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    posthogHost: 'https://eu.posthog.com',
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    posthogHost: 'https://analytics.yourcompany.com',
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

Debug Mode

Enable detailed console logging for troubleshooting:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    debug: true, // Enable debug logging
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

When enabled, you'll see detailed logs for:

Event collection
Network requests to PostHog
Performance metrics
Navigation tracking

Batch Size

Control how many events are batched before sending to PostHog:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    batchSize: 10, // Default is 10
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

Recommendations:

Low traffic apps: Use default (10) or lower (5)
High traffic apps: Increase to 20-50 to reduce network requests
Real-time needs: Use 1 to send events immediately

Flush Interval

Set how often (in milliseconds) to flush batched events to PostHog:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    flushInterval: 5000, // Default is 5000ms (5 seconds)
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

Recommendations:

Default (5000ms): Good for most applications
Real-time dashboards: Reduce to 2000-3000ms
Low priority tracking: Increase to 10000-15000ms to reduce API calls

Automatic Route Tracking

Control whether navigation events are automatically tracked:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    autoTrackRoutes: true, // Default is true
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

When enabled, HydrateBeer automatically tracks:

Page views
Route changes
Navigation timing
Referrer information

Set to false if you want to manually track navigation events.

Component Performance Tracking

Enable automatic performance tracking for React components:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    trackComponentPerformance: true, // Default is true
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

When enabled, tracks:

Component render times
Mount/unmount timing
Re-render frequency
Performance bottlenecks

Error Tracking

Automatically capture and report errors to PostHog:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    trackErrors: true, // Default is true
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

Captures:

Unhandled exceptions
Promise rejections
Component error boundaries
Stack traces and context

Session Tracking

Track user sessions and session duration:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    trackSessions: true, // Default is true
  }}
>
  {/* Your app */}
</HydrateBeerProvider>

Tracks:

Session start/end
Session duration
Pages per session
Session properties

Complete Configuration Example

Here's a full example with all available options:

import { HydrateBeerProvider } from 'hydrate-beer/react';

function App() {
  return (
    <HydrateBeerProvider
      config={{
        // Required
        posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
        
        // Optional
        posthogHost: 'https://us.posthog.com', // or 'https://eu.posthog.com'
        debug: false,
        batchSize: 10,
        flushInterval: 5000,
        autoTrackRoutes: true,
        trackComponentPerformance: true,
        trackErrors: true,
        trackSessions: true,
      }}
    >
      {/* Your app */}
    </HydrateBeerProvider>
  );
}

Environment-Specific Configuration

Development vs Production

Use different configurations for different environments:

// app/layout.tsx or pages/_app.tsx
import { HydrateBeerProvider } from 'hydrate-beer/react';

const isDevelopment = process.env.NODE_ENV === 'development';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <HydrateBeerProvider
          config={{
            posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
            debug: isDevelopment,
            batchSize: isDevelopment ? 1 : 10,
            flushInterval: isDevelopment ? 1000 : 5000,
          }}
        >
          {children}
        </HydrateBeerProvider>
      </body>
    </html>
  );
}

// src/App.tsx
import { HydrateBeerProvider } from 'hydrate-beer/react';

const isDevelopment = process.env.NODE_ENV === 'development';

function App() {
  return (
    <HydrateBeerProvider
      config={{
        posthogApiKey: process.env.REACT_APP_HYDRATE_BEER_POSTHOG_API_KEY!,
        debug: isDevelopment,
        batchSize: isDevelopment ? 1 : 10,
      }}
    >
      {/* Your app */}
    </HydrateBeerProvider>
  );
}

// src/main.tsx
import { HydrateBeerProvider } from 'hydrate-beer/react';

const isDevelopment = import.meta.env.DEV;

function App() {
  return (
    <HydrateBeerProvider
      config={{
        posthogApiKey: import.meta.env.VITE_HYDRATE_BEER_POSTHOG_API_KEY!,
        debug: isDevelopment,
        batchSize: isDevelopment ? 1 : 10,
      }}
    >
      {/* Your app */}
    </HydrateBeerProvider>
  );
}

Multiple Environments

Configure different PostHog projects for staging and production:

// .env.development
NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY=phc_dev_xxx
NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_HOST=https://us.posthog.com

// .env.production
NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY=phc_prod_yyy
NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_HOST=https://eu.posthog.com

Configuration File

For complex setups, use hydrate-beer.config.ts:

// hydrate-beer.config.ts
import type { HydrateBeerConfig } from 'hydrate-beer';

const config: HydrateBeerConfig = {
  posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
  posthogHost: 'https://us.posthog.com',
  debug: process.env.NODE_ENV === 'development',
  batchSize: 10,
  flushInterval: 5000,
  autoTrackRoutes: true,
  trackComponentPerformance: true,
  trackErrors: true,
  trackSessions: true,
};

export default config;

Then import in your app:

import { HydrateBeerProvider } from 'hydrate-beer/react';
import config from '../hydrate-beer.config';

function App() {
  return (
    <HydrateBeerProvider config={config}>
      {/* Your app */}
    </HydrateBeerProvider>
  );
}

TypeScript Types

All configuration options are fully typed:

interface HydrateBeerConfig {
  // Required
  posthogApiKey: string;
  
  // Optional
  posthogHost?: string;
  debug?: boolean;
  batchSize?: number;
  flushInterval?: number;
  autoTrackRoutes?: boolean;
  trackComponentPerformance?: boolean;
  trackErrors?: boolean;
  trackSessions?: boolean;
}

Best Practices

Security

Always use environment variables for your PostHog API key. Never commit API keys to version control.

// ✅ Good
posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!

// ❌ Bad
posthogApiKey: 'phc_abc123...'

Performance

Use appropriate batch sizes: Larger batches reduce network overhead but delay analytics visibility
Adjust flush intervals: Balance between real-time insights and API call frequency
Disable unused features: Turn off tracking features you don't need

// High-performance configuration
<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    batchSize: 20, // Larger batches
    flushInterval: 10000, // Less frequent flushes
    trackComponentPerformance: false, // Disable if not needed
  }}
>

Development

Enable debug mode during development to see what's being tracked:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    debug: process.env.NODE_ENV === 'development',
    batchSize: 1, // Send immediately in dev
    flushInterval: 1000, // Flush every second
  }}
>

Production

Optimize for production:

<HydrateBeerProvider
  config={{
    posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
    debug: false,
    batchSize: 15,
    flushInterval: 5000,
    autoTrackRoutes: true,
    trackComponentPerformance: true,
    trackErrors: true,
    trackSessions: true,
  }}
>

Configuration Validation

HydrateBeer validates your configuration on initialization. Common errors:

Missing API Key

Error: PostHog API key is required. Please provide posthogApiKey in your configuration.

Solution: Add your PostHog API key to environment variables and configuration.

Invalid API Key Format

Error: Invalid PostHog API key format. Expected format: phc_...

Solution: Verify you're using your Project API Key from PostHog settings, not your personal API key.

Invalid Host URL

Error: posthogHost must be a valid HTTPS URL

Solution: Ensure your PostHog host starts with https://

Next Steps

Quick Start - Get started with HydrateBeer
API Reference - View all available methods
Tracking Guide - Learn about custom event tracking
PostHog Dashboard - View your analytics in PostHog

Configuration

On this page