Providers Overview

Providers are plugins that send your events to analytics services. @stacksee/analytics includes official support for popular services and makes it easy to add custom providers.

Open-source product analytics with feature flags and session replay

mail

Bento

Email marketing and automation platform with event tracking

shield

Pirsch

Privacy-focused, cookie-free web analytics

bell

EmitKit

Event notifications and activity feeds with rich metadata

arrow-right-left

Proxy Provider

Route events through your server to bypass ad-blockers

Quick Setup

PostHog

pnpm install posthog-js posthog-node

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

new PostHogClientProvider({
  token: 'your-posthog-api-key',
  api_host: 'https://app.posthog.com'
})

Full PostHog Documentation →

Bento

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

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

new BentoClientProvider({
  siteUuid: 'your-bento-site-uuid'
})

Full Bento Documentation →

Pirsch

pnpm install pirsch-sdk

import { PirschClientProvider } from '@stacksee/analytics/providers/client';

new PirschClientProvider({
  identificationCode: 'your-pirsch-identification-code',
  hostname: 'example.com'
})

Full Pirsch Documentation →

EmitKit

# Server-only: pnpm install @emitkit/js

import { EmitKitServerProvider } from '@stacksee/analytics/providers/server';

new EmitKitServerProvider({
  apiKey: 'emitkit_xxxxx',
  channelName: 'analytics'
})

Full EmitKit Documentation →

Using Multiple Providers

Combine providers to leverage different capabilities:

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

const analytics = createClientAnalytics({
  providers: [
    // PostHog for product analytics and feature flags
    new PostHogClientProvider({
      token: import.meta.env.VITE_POSTHOG_KEY
    }),

    // Bento for email marketing automation
    new BentoClientProvider({
      siteUuid: import.meta.env.VITE_BENTO_SITE_UUID
    })
  ]
});

// Events sent to all providers
analytics.track('user_signed_up', {
  email: 'user@example.com',
  plan: 'pro'
});

Environment-Specific Imports

Always use the correct import path to avoid bundling issues:

// ✅ Correct - only browser-compatible code
import { PostHogClientProvider } from '@stacksee/analytics/providers/client';

// ❌ Wrong - may bundle Node.js dependencies
import { PostHogClientProvider } from '@stacksee/analytics/providers';

// ✅ Correct - only Node.js code
import { PostHogServerProvider } from '@stacksee/analytics/providers/server';

// ❌ Wrong - may bundle browser code
import { PostHogServerProvider } from '@stacksee/analytics/providers';

Configuration Best Practices

1. Use Environment Variables

new PostHogClientProvider({
  token: import.meta.env.VITE_POSTHOG_KEY,  // Vite
  // OR
  token: process.env.NEXT_PUBLIC_POSTHOG_KEY  // Next.js
})

2. Enable Debug in Development

new PostHogClientProvider({
  token: 'xxx',
  debug: import.meta.env.DEV  // or process.env.NODE_ENV === 'development'
})

3. Conditional Providers

const providers = [
  new PostHogClientProvider({ token: 'xxx' })
];

// Only add Bento in production
if (import.meta.env.PROD) {
  providers.push(new BentoClientProvider({ siteUuid: 'xxx' }));
}

const analytics = createClientAnalytics({ providers });

4. Graceful Degradation

const analytics = createClientAnalytics({
  providers: [
    new PostHogClientProvider({
      token: 'xxx',
      enabled: !!import.meta.env.VITE_POSTHOG_KEY  // Disable if no key
    })
  ]
});

Custom Providers

Want to integrate with a different analytics service? Create a custom provider:

import { BaseAnalyticsProvider, BaseEvent, EventContext } from '@stacksee/analytics';

export class CustomProvider extends BaseAnalyticsProvider {
  name = 'CustomProvider';

  async initialize(): Promise<void> {
    // Initialize your SDK
  }

  track(event: BaseEvent, context?: EventContext): void {
    // Send event to your service
  }

  identify(userId: string, traits?: Record<string, unknown>): void {
    // Identify user
  }

  // ... implement other required methods
}