Quick Start

This guide will get you tracking analytics events in under 5 minutes.

Installation

Install the Core Library

pnpm install @stacksee/analytics

Install Provider SDKs

Choose which analytics services you want to use:

pnpm install posthog-js posthog-node

# Client-side: No installation needed (uses CDN)
# Server-side:
pnpm install @bentonow/bento-node-sdk

pnpm install pirsch-sdk

Define Your Events

Create a file to define your application events with full type safety:

lib/events.ts

import type { CreateEventDefinition, EventCollection } from '@stacksee/analytics';

export const appEvents = {
  userSignedUp: {
    name: 'user_signed_up',
    category: 'user',
    properties: {} as {
      email: string;
      plan: 'free' | 'pro' | 'enterprise';
      referralSource?: string;
    }
  },

  buttonClicked: {
    name: 'button_clicked',
    category: 'engagement',
    properties: {} as {
      buttonId: string;
      location: string;
    }
  },

  featureUsed: {
    name: 'feature_used',
    category: 'engagement',
    properties: {} as {
      featureName: string;
      userId: string;
    }
  }
} as const satisfies EventCollection<Record<string, CreateEventDefinition<string>>>;

// Export types for use in your app
export type AppEvents = typeof appEvents;

Client-Side Setup

Initialize Analytics

Create your analytics instance with your chosen providers:

lib/analytics.ts

import { createClientAnalytics } from '@stacksee/analytics/client';
import { PostHogClientProvider } from '@stacksee/analytics/providers/client';
import type { AppEvents } from './events';

export const analytics = createClientAnalytics<AppEvents>({
  providers: [
    new PostHogClientProvider({
      token: 'your-posthog-api-key',
      api_host: 'https://app.posthog.com'
    })
  ],
  debug: import.meta.env.DEV
});

lib/analytics.ts

import { createClientAnalytics } from '@stacksee/analytics/client';
import { BentoClientProvider } from '@stacksee/analytics/providers/client';
import type { AppEvents } from './events';

export const analytics = createClientAnalytics<AppEvents>({
  providers: [
    // Bento doesn't support anonymous page views - exclude by default
    {
      provider: new BentoClientProvider({
        siteUuid: 'your-bento-site-uuid'
      }),
      exclude: ['pageView']
    }
  ],
  debug: import.meta.env.DEV
});

lib/analytics.ts

import { createClientAnalytics } from '@stacksee/analytics/client';
import { PirschClientProvider } from '@stacksee/analytics/providers/client';
import type { AppEvents } from './events';

export const analytics = createClientAnalytics<AppEvents>({
  providers: [
    new PirschClientProvider({
      identificationCode: 'your-pirsch-identification-code',
      hostname: 'example.com'
    })
  ],
  debug: import.meta.env.DEV
});

Track Events

Import and use your analytics instance anywhere in your app:

components/SignupButton.tsx

import { analytics } from '@/lib/analytics';

export function SignupButton() {
  const handleClick = () => {
    // Full type safety - autocomplete works!
    analytics.track('button_clicked', {
      buttonId: 'signup-cta',
      location: 'hero'
    });
  };

  return <button onClick={handleClick}>Sign Up</button>;
}

Identify Users

Call identify() when users log in to attach user context to all events:

// After successful login
analytics.identify('user-123', {
  email: 'user@example.com',
  plan: 'pro',
  name: 'John Doe'
});

// All subsequent events automatically include this context
analytics.track('feature_used', {
  featureName: 'export',
  userId: 'user-123'
});

Server-Side Setup

Initialize Server Analytics

lib/server-analytics.ts

import { createServerAnalytics } from '@stacksee/analytics/server';
import { PostHogServerProvider } from '@stacksee/analytics/providers/server';
import type { AppEvents } from './events';

export const serverAnalytics = createServerAnalytics<AppEvents>({
  providers: [
    new PostHogServerProvider({
      apiKey: process.env.POSTHOG_API_KEY!,
      host: process.env.POSTHOG_HOST
    })
  ],
  debug: process.env.NODE_ENV === 'development'
});

lib/server-analytics.ts

import { createServerAnalytics } from '@stacksee/analytics/server';
import { BentoServerProvider } from '@stacksee/analytics/providers/server';
import type { AppEvents } from './events';

export const serverAnalytics = createServerAnalytics<AppEvents>({
  providers: [
    // Bento doesn't support anonymous page views - exclude by default
    {
      provider: new BentoServerProvider({
        siteUuid: process.env.BENTO_SITE_UUID!,
        authentication: {
          publishableKey: process.env.BENTO_PUBLISHABLE_KEY!,
          secretKey: process.env.BENTO_SECRET_KEY!
        }
      }),
      exclude: ['pageView']
    }
  ],
  debug: process.env.NODE_ENV === 'development'
});

lib/server-analytics.ts

import { createServerAnalytics } from '@stacksee/analytics/server';
import { PirschServerProvider } from '@stacksee/analytics/providers/server';
import type { AppEvents } from './events';

export const serverAnalytics = createServerAnalytics<AppEvents>({
  providers: [
    new PirschServerProvider({
      hostname: process.env.PIRSCH_HOSTNAME!,
      clientSecret: process.env.PIRSCH_ACCESS_KEY!
    })
  ],
  debug: process.env.NODE_ENV === 'development'
});

Track Server Events

app/api/users/route.ts

import { serverAnalytics } from '@/lib/server-analytics';

export async function POST(req: Request) {
  const body = await req.json();

  // Track with user context
  await serverAnalytics.track('user_signed_up', {
    email: body.email,
    plan: body.plan,
    referralSource: 'landing-page'
  }, {
    userId: body.userId,
    user: {
      email: body.email,
      traits: {
        plan: body.plan
      }
    }
  });

  // Important: Always shutdown in serverless environments
  await serverAnalytics.shutdown();

  return new Response('OK');
}

Using Multiple Providers

You can use multiple analytics services simultaneously:

lib/analytics.ts

import { createClientAnalytics } from '@stacksee/analytics/client';
import { PostHogClientProvider, BentoClientProvider } from '@stacksee/analytics/providers/client';

export const analytics = createClientAnalytics<AppEvents>({
  providers: [
    // Product analytics with PostHog (all events)
    new PostHogClientProvider({
      token: import.meta.env.VITE_POSTHOG_KEY!
    }),

    // Email marketing with Bento (exclude anonymous page views)
    {
      provider: new BentoClientProvider({
        siteUuid: import.meta.env.VITE_BENTO_SITE_UUID!
      }),
      exclude: ['pageView']
    }
  ]
});

// One call, all providers receive the event
analytics.track('user_signed_up', {
  email: 'user@example.com',
  plan: 'pro'
});