Your First Event

Let's get you tracking your first event in under 2 minutes. This tutorial will walk you through the absolute minimum to see analytics working.

Already installed? Jump to Step 2.

Need a specific framework? Check out Next.js or SvelteKit guides.

Install the Library

npm install @stacksee/analytics

That's it! The core library has zero dependencies and is ready to use.

Don't have an analytics provider yet? No problem! We'll start with console logging to see how it works.

Define Your First Event

Create a file to define your analytics events:

lib/events.ts

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

export const appEvents = {
  buttonClicked: {
    name: 'button_clicked',
    category: 'engagement',
    properties: {} as {
      buttonId: string;
      location: string;
    }
  }
} as const satisfies EventCollection<Record<string, CreateEventDefinition<string>>>;

What did we just do?

We defined a button_clicked event with two required properties:

buttonId - Which button was clicked
location - Where in the app the button lives

TypeScript now knows exactly what data this event needs!

Create Your Analytics Instance

For now, we'll use a simple console logger to see events:

lib/analytics.ts

import { createClientAnalytics } from '@stacksee/analytics/client';
import { BaseAnalyticsProvider } from '@stacksee/analytics';
import type { appEvents } from './events';

// Simple console logger provider
class ConsoleProvider extends BaseAnalyticsProvider {
  name = 'ConsoleProvider';

  track(event: any) {
    console.log('📊 Event tracked:', event);
  }

  identify(userId: string, traits: any) {
    console.log('👤 User identified:', userId, traits);
  }

  pageView() {
    console.log('📄 Page view tracked');
  }

  pageLeave() {
    console.log('👋 Page leave tracked');
  }

  reset() {
    console.log('🔄 Analytics reset');
  }
}

export const analytics = createClientAnalytics<typeof appEvents>({
  providers: [new ConsoleProvider()],
  debug: true
});

Using a real analytics service? Replace ConsoleProvider with a real provider:

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

export const analytics = createClientAnalytics<typeof appEvents>({
  providers: [
    new PostHogClientProvider({
      token: 'your-posthog-key'
    })
  ]
});

See provider guides for setup instructions.

Track Your First Event

Now use it anywhere in your app:

components/Button.tsx

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

export function MyButton() {
  const handleClick = () => {
    analytics.track('buttonClicked', {
      buttonId: 'hero-cta',
      location: 'homepage'
    });

    console.log('Button clicked!');
  };

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

components/Button.vue

<script setup lang="ts">
import { analytics } from '@/lib/analytics';

const handleClick = () => {
  analytics.track('buttonClicked', {
    buttonId: 'hero-cta',
    location: 'homepage'
  });

  console.log('Button clicked!');
};
</script>

<template>
  <button @click="handleClick">
    Click Me
  </button>
</template>

components/Button.svelte

<script lang="ts">
  import { analytics } from '$lib/analytics';

  function handleClick() {
    analytics.track('buttonClicked', {
      buttonId: 'hero-cta',
      location: 'homepage'
    });

    console.log('Button clicked!');
  }
</script>

<button on:click={handleClick}>
  Click Me
</button>

main.ts

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

const button = document.querySelector('#my-button');

button?.addEventListener('click', () => {
  analytics.track('buttonClicked', {
    buttonId: 'hero-cta',
    location: 'homepage'
  });

  console.log('Button clicked!');
});

See It in Action

Open your browser console and click the button. You should see:

📊 Event tracked: {
  action: 'button_clicked',
  category: 'engagement',
  properties: {
    buttonId: 'hero-cta',
    location: 'homepage'
  }
}

🎉 Congratulations! You just tracked your first event!

What You Just Built

In under 2 minutes, you:

✅ Installed @stacksee/analytics
✅ Defined a type-safe event
✅ Created an analytics instance
✅ Tracked your first event
✅ Saw it in the console

Try These Next

Add More Events

Let's add a few more events to track:

lib/events.ts

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

  // New: Track form submissions
  formSubmitted: {
    name: 'form_submitted',
    category: 'conversion',
    properties: {} as {
      formId: string;
      formType: 'signup' | 'contact' | 'newsletter';
    }
  },

  // New: Track feature usage
  featureUsed: {
    name: 'feature_used',
    category: 'engagement',
    properties: {} as {
      featureName: string;
    }
  }
} as const satisfies EventCollection<Record<string, CreateEventDefinition<string>>>;

Now track them:

// Track form submission
analytics.track('formSubmitted', {
  formId: 'newsletter-signup',
  formType: 'newsletter'
});

// Track feature usage
analytics.track('featureUsed', {
  featureName: 'export-data'
});

Identify Users

Once a user logs in, identify them:

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

// All subsequent events automatically include user context
analytics.track('featureUsed', {
  featureName: 'export'
});

See the Identifying Users guide for more details.

Add a Real Provider

Replace the console logger with a real analytics provider:

Install the SDK:

npm install posthog-js

Update your analytics instance:

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<typeof appEvents>({
  providers: [
    new PostHogClientProvider({
      token: 'your-posthog-key',
      api_host: 'https://app.posthog.com'
    })
  ]
});

Get your API key from PostHog

Full PostHog setup guide →

No installation needed for client-side! Update your analytics instance:

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<typeof appEvents>({
  providers: [
    new BentoClientProvider({
      siteUuid: 'your-bento-site-uuid'
    })
  ]
});

Get your site UUID from Bento

Full Bento setup guide →

Install the SDK:

npm install pirsch-sdk

Update your analytics instance:

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<typeof appEvents>({
  providers: [
    new PirschClientProvider({
      identificationCode: 'your-pirsch-code',
      hostname: 'example.com'
    })
  ]
});

Get your identification code from Pirsch

Full Pirsch setup guide →

Common Questions

Do I need an analytics provider right away?

No! You can start with the console logger and add a real provider later. The beauty of @stacksee/analytics is that your tracking code doesn't change when you switch providers.

Can I use multiple providers?

Yes! Just add them to the providers array:

const analytics = createClientAnalytics({
  providers: [
    new PostHogClientProvider({ token: 'xxx' }),
    new BentoClientProvider({ siteUuid: 'xxx' })
  ]
});

Events are sent to all providers automatically.

What about TypeScript autocomplete?

It just works! Once you define your events with as const satisfies EventCollection<...>, TypeScript will autocomplete event names and properties everywhere you use analytics.track().

Try typing analytics.track(' in your IDE and watch the magic happen!

How do I track page views?

Page views are typically tracked automatically by your framework. See the framework guides for details:

Or track manually:

analytics.pageView({
  path: window.location.pathname,
  title: document.title
});

Your First Event

Install the Library

Define Your First Event

Create Your Analytics Instance

Track Your First Event

See It in Action

What You Just Built

Try These Next

Add More Events

Identify Users

Add a Real Provider

Common Questions

Do I need an analytics provider right away?

Can I use multiple providers?

What about TypeScript autocomplete?

How do I track page views?

Next Steps

Identifying Users

Core Concepts

Framework Guides

Providers

On this page