Core Concepts Overview

This section covers the fundamental concepts you need to master @stacksee/analytics. Each guide goes deep into a specific topic with examples and best practices.

What You'll Learn

Learning Path

If you're new to @stacksee/analytics, we recommend reading these guides in order:

1. Events - Start here to understand how to define and track events
2. Providers - Learn how events get delivered to analytics services
3. Client vs Server - Understand when and how to track in different environments
4. Type Safety - Master TypeScript features for error-free tracking

Prerequisites

Before diving into these concepts, make sure you've:

• ✅ Completed Your First Event tutorial
• ✅ Installed @stacksee/analytics and at least one provider
• ✅ Have a basic understanding of TypeScript

Quick Reference

Event Definition Pattern

export const appEvents = {
  eventName: {
    name: 'event_name',
    category: 'category',
    properties: {} as {
      // Type-safe properties
    }
  }
} as const satisfies EventCollection<Record<string, CreateEventDefinition<string>>>;

Client-Side Tracking

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

// Track event
analytics.track('eventName', { /* properties */ });

// Identify user
analytics.identify('user-id', { /* traits */ });

// Reset on logout
analytics.reset();

Server-Side Tracking

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

// Track with user context
await serverAnalytics.track('eventName', { /* properties */ }, {
  userId: 'user-id',
  user: { /* user data */ }
});

// Always shutdown in serverless
await serverAnalytics.shutdown();

Common Questions

When should I use client-side vs server-side tracking?

• Client-side: User interactions, page views, UI events
• Server-side: API calls, background jobs, critical events

See Client vs Server for detailed guidance.

How do I use multiple analytics providers?

Add them to the providers array when creating your analytics instance:

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

Events are automatically sent to all providers. See Providers for more.

How does type safety work?

TypeScript infers event names and properties from your event definitions. This gives you autocomplete and compile-time errors for typos or wrong property types. See Type Safety for the full picture.

Next Steps

Ready to dive deep? Start with Events →

Or jump to a specific topic:

• Providers →
• Client vs Server →
• Type Safety →