Step 1: Create PostHog Account

Sign up for free at posthog.com
Create a new project
Copy your Project API Key from Project Settings

Step 2: Initialize

Run the CLI in your React/Next.js project:

npx hydrate-beer-cli init

You'll be prompted to:

Provide your PostHog Project API Key
Select PostHog instance (US Cloud, EU Cloud, or Self-hosted)

The CLI will:

Create hydrate-beer.config.ts with PostHog configuration
Create/update .env.local with your API key
Auto-install hydrate-beer

Example Output

Initializing HydrateBeer...

Detected Next.js project

PostHog Setup

  HydrateBeer uses PostHog to store your analytics data.
  1. Create a FREE account at: https://posthog.com
  2. Create a new project
  3. Copy your Project API Key from: Project Settings -> Project API Key

? Enter your PostHog Project API Key: phc_...
? Select your PostHog instance: › PostHog Cloud (US)
? Install hydrate-beer? › Yes

Created hydrate-beer.config.ts
Updated .env.local with PostHog API key
Installed hydrate-beer

Done!

  PostHog Configuration:
    API Key: phc_M0Qw4j...
    Host: https://us.posthog.com

  Next steps:
  1. Add HydrateBeerProvider to your app (see docs)
  2. View analytics in PostHog: https://app.us.posthog.com
  3. Filter by events: hydratebeer_*

Step 3: Add the Provider

Next.js App Router

Update your root layout to use client component:

app/layout.tsx

"use client";

import { HydrateBeerProvider } from 'hydrate-beer';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <HydrateBeerProvider
          config={{
            posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
            posthogHost: 'https://us.posthog.com',
            debug: true,
          }}
        >
          {children}
        </HydrateBeerProvider>
      </body>
    </html>
  );
}

Next.js Pages Router

pages/_app.tsx

import { HydrateBeerProvider } from 'hydrate-beer';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <HydrateBeerProvider
      config={{
        posthogApiKey: process.env.NEXT_PUBLIC_HYDRATE_BEER_POSTHOG_API_KEY!,
        posthogHost: 'https://us.posthog.com',
        debug: true,
      }}
    >
      <Component {...pageProps} />
    </HydrateBeerProvider>
  );
}

Create React App / Vite

src/main.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { HydrateBeerProvider } from 'hydrate-beer';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <HydrateBeerProvider
      config={{
        posthogApiKey: import.meta.env.VITE_HYDRATE_BEER_POSTHOG_API_KEY,
        posthogHost: 'https://us.posthog.com',
        debug: true,
      }}
    >
      <App />
    </HydrateBeerProvider>
  </React.StrictMode>
);

Step 4: Track Custom Events

Use the useHydrateBeer hook to track custom events:

import { useHydrateBeer } from 'hydrate-beer';

export function MyComponent() {
  const { trackCustomEvent, trackError } = useHydrateBeer();

  const handleClick = () => {
    trackCustomEvent('button_clicked', {
      buttonName: 'submit',
      page: 'checkout',
    });
  };

  return (
    <button onClick={handleClick}>
      Submit
    </button>
  );
}

Step 5: View Analytics

PostHog Dashboard

Open posthog.com
Navigate to your project
Go to Activity → Events
All HydrateBeer events are prefixed with hydratebeer_
Create custom insights and dashboards

CLI Monitor Command

Open PostHog dashboard directly from CLI:

npx hydrate-beer-cli monitor

This command reads your config and opens PostHog in your browser showing available events.

What Gets Tracked?

HydrateBeer automatically tracks:

Page Views - Initial page loads
Navigation - Client-side route changes
Hydration - React hydration performance
Renders - Component render times
Slow Renders - Renders exceeding threshold
Custom Events - Your tracked events
Errors - Caught errors with context

All events are sent to PostHog in real-time with automatic batching and retry logic.

Quick Start

Step 1: Create PostHog Account

Step 2: Initialize

Example Output

Step 3: Add the Provider

Next.js App Router

Next.js Pages Router

Create React App / Vite

Step 4: Track Custom Events

Step 5: View Analytics

PostHog Dashboard

CLI Monitor Command

What Gets Tracked?

Next Steps

Configuration

API Reference

Tracking Guide

Need Help?

On this page