Installation

Get @stacksee/analytics installed and ready to track events in under 2 minutes.

Quick Install

npm install @stacksee/analytics

npm install posthog-js posthog-node

# Client-side: No installation needed (uses CDN)

# Server-side only:
npm install @bentonow/bento-node-sdk

npm install pirsch-sdk

# Install SDKs for all providers you want to use
npm install posthog-js posthog-node @bentonow/bento-node-sdk pirsch-sdk

Package Manager Options

Choose your preferred package manager:

npm install @stacksee/analytics

pnpm install @stacksee/analytics

yarn add @stacksee/analytics

bun add @stacksee/analytics

What Gets Installed

Core Library (@stacksee/analytics)

• Size: ~10KB gzipped
• Dependencies: Zero
• Exports: Client, server, and shared types
• Tree-shakeable: Only bundle what you use

Provider SDKs

Provider SDKs are separate packages maintained by each analytics service:

Verify Installation

Check that everything is installed correctly:

npm list @stacksee/analytics

You should see:

your-project@1.0.0
└── @stacksee/analytics@x.x.x

TypeScript Support

@stacksee/analytics is written in TypeScript and includes full type definitions.

No additional setup required!

// Types work automatically
import { createClientAnalytics } from '@stacksee/analytics/client';
//       ↑ Full autocomplete and type checking

Environment Setup

Client-Side Environment Variables

Create environment variables for your API keys:

VITE_POSTHOG_KEY=your-posthog-api-key
VITE_BENTO_SITE_UUID=your-bento-site-uuid
VITE_PIRSCH_IDENTIFICATION_CODE=your-pirsch-code

const analytics = createClientAnalytics({
  providers: [
    new PostHogClientProvider({
      token: import.meta.env.VITE_POSTHOG_KEY
    })
  ]
});

NEXT_PUBLIC_POSTHOG_KEY=your-posthog-api-key
NEXT_PUBLIC_BENTO_SITE_UUID=your-bento-site-uuid
NEXT_PUBLIC_PIRSCH_CODE=your-pirsch-code

const analytics = createClientAnalytics({
  providers: [
    new PostHogClientProvider({
      token: process.env.NEXT_PUBLIC_POSTHOG_KEY
    })
  ]
});

PUBLIC_POSTHOG_KEY=your-posthog-api-key
PUBLIC_BENTO_SITE_UUID=your-bento-site-uuid
PUBLIC_PIRSCH_CODE=your-pirsch-code

import { PUBLIC_POSTHOG_KEY } from '$env/static/public';

const analytics = createClientAnalytics({
  providers: [
    new PostHogClientProvider({
      token: PUBLIC_POSTHOG_KEY
    })
  ]
});

REACT_APP_POSTHOG_KEY=your-posthog-api-key
REACT_APP_BENTO_SITE_UUID=your-bento-site-uuid
REACT_APP_PIRSCH_CODE=your-pirsch-code

const analytics = createClientAnalytics({
  providers: [
    new PostHogClientProvider({
      token: process.env.REACT_APP_POSTHOG_KEY
    })
  ]
});

Server-Side Environment Variables

For server-side tracking, use non-public environment variables:

# Server-only - NOT prefixed with PUBLIC_/NEXT_PUBLIC_/etc
POSTHOG_API_KEY=your-posthog-api-key
BENTO_SECRET_KEY=your-bento-secret-key
PIRSCH_ACCESS_KEY=your-pirsch-access-key

// Server-side code only
const serverAnalytics = createServerAnalytics({
  providers: [
    new PostHogServerProvider({
      apiKey: process.env.POSTHOG_API_KEY
    })
  ]
});

Common Issues

Module Not Found

If you see Cannot find module '@stacksee/analytics/client':

1. Check your package.json: Ensure @stacksee/analytics is installed
2. Clear node_modules: Run rm -rf node_modules && npm install
3. Check import path: Use /client or /server, not the root package

// ✅ Correct
import { createClientAnalytics } from '@stacksee/analytics/client';

// ❌ Wrong
import { createClientAnalytics } from '@stacksee/analytics';

TypeScript Errors

If you see TypeScript errors about missing types:

1. Update TypeScript: Ensure you're using TypeScript 4.7+
2. Check tsconfig.json: Enable moduleResolution: "bundler" or "node16"

{
  "compilerOptions": {
    "moduleResolution": "bundler",  // or "node16"
    "esModuleInterop": true,
    "skipLibCheck": false
  }
}

Provider SDK Errors

If provider SDKs fail to load:

1. Check SDK installation: Run npm list posthog-js (or other SDK)
2. Install peer dependencies: Some SDKs have peer dependencies
3. Check SDK compatibility: Ensure SDK versions are compatible

# Example: PostHog SDK not found
npm install posthog-js posthog-node

# Example: Bento SDK not found
npm install @bentonow/bento-node-sdk

Upgrading

To upgrade to the latest version:

npm install @stacksee/analytics@latest

Check the changelog for breaking changes.

Uninstalling

To completely remove @stacksee/analytics:

# Remove core library
npm uninstall @stacksee/analytics

# Remove provider SDKs
npm uninstall posthog-js posthog-node @bentonow/bento-node-sdk pirsch-sdk

Next Steps