Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lobehub/lobe-analytics

📍 Lobe Analytics - a modern, type-safe analytics library for tracking user events across multiple providers.
https://github.com/lobehub/lobe-analytics

analytics posthog

Last synced: about 2 months ago
JSON representation

📍 Lobe Analytics - a modern, type-safe analytics library for tracking user events across multiple providers.

Awesome Lists containing this project

README 

          












Lobe Analytics



A modern, type-safe analytics library for tracking user events across multiple providers, built by LobeHub



[![][npm-release-shield]][npm-release-link]

[![][github-releasedate-shield]][github-releasedate-link]

[![][github-action-test-shield]][github-action-test-link]

[![][github-action-release-shield]][github-action-release-link]


[![][github-contributors-shield]][github-contributors-link]

[![][github-forks-shield]][github-forks-link]

[![][github-stars-shield]][github-stars-link]

[![][github-issues-shield]][github-issues-link]

[![][github-license-shield]][github-license-link]



[Changelog](./CHANGELOG.md) · [Report Bug][github-issues-link] · [Request Feature][github-issues-link]



![](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png)






Table of contents



#### TOC



- [✨ Features](#-features)

- [📦 Installation](#-installation)

- [⚠️ **Client-side vs Server-side Usage**](#️-client-side-vs-server-side-usage)

  - [🌐 **Client-side Usage** (Browser Environment)](#-client-side-usage-browser-environment)

  - [🖥️ **Server-side Usage** (Node.js Environment)](#️-server-side-usage-nodejs-environment)

- [Import Structure](#import-structure)

- [🚀 Quick Start](#-quick-start)

  - [Basic Usage](#basic-usage)

  - [Global Instance Management](#global-instance-management)

  - [React Integration](#react-integration)

  - [SPM (Source Page Medium) Auto-Prefixing](#spm-source-page-medium-auto-prefixing)

- [📖 API Reference](#-api-reference)

  - [Core Functions](#core-functions)

  - [Global Instance Management](#global-instance-management-1)

  - [React Hooks & Provider](#react-hooks--provider)

  - [Types](#types)

- [🛠️ Development](#️-development)

  - [Project Structure](#project-structure)

- [Examples](#examples)

- [🤝 Contributing](#-contributing)



####



## ✨ Features



- 🎯 **Type-safe** - Full TypeScript support with predefined events

- 🔌 **Multi-provider** - Built-in PostHog support, extensible for other providers

- 🌐 **Global Instance Management** - Singleton pattern and named global instances

- 📊 **SPM Auto-Prefixing** - Automatic Source Page Medium tracking with business prefixes

- ⚛️ **React integration** - Enhanced Provider with auto-registration and hooks

- 🎛️ **Easy configuration** - Simple setup with business context

- 🪶 **Lightweight** - Minimal dependencies and optimized bundle size

- 🔧 **Developer-friendly** - Comprehensive error handling and debugging

- 🧪 **Test-friendly** - Built-in reset and cleanup functions



## 📦 Installation



To install `@lobehub/analytics`, run the following command:



```bash

npm install @lobehub/analytics



# Additional installation for server-side usage

npm install posthog-node # Server-side only

```



This library includes PostHog analytics provider out of the box. For React integration:



```bash

npm install react # if not already installed

```



## ⚠️ **Client-side vs Server-side Usage**



### 🌐 **Client-side Usage** (Browser Environment)



```typescript

import { createAnalytics } from '@lobehub/analytics';



const analytics = createAnalytics({

  business: 'my-app',

  providers: {

    posthog: { enabled: true, key: 'client_key' },

  },

});

```



### 🖥️ **Server-side Usage** (Node.js Environment)



```typescript

import { createServerAnalytics } from '@lobehub/analytics/server';



const analytics = createServerAnalytics({

  business: 'my-app',

  providers: {

    // ✅ Client-side PostHog (browser compatible)

    posthog: {

      enabled: true,

      key: 'phc_xxxxx',

      api_host: 'https://app.posthog.com',

    },

    // ✅ Server-side PostHog (Node.js only)

    posthogNode: {

      enabled: true,

      key: 'server_key',

      host: 'https://app.posthog.com',

    },

  },

});

```



> **🔥 Separation Solution**: Clear entry point separation ensures `posthogNode` is completely excluded from client-side builds!



## Import Structure



The library provides separate entry points for client-side, server-side, and React integration:



```typescript

// Client-side analytics (browser safe)

import { AnalyticsManager, createAnalytics } from '@lobehub/analytics';

// Global instance management

import {

  createSingletonAnalytics,

  getGlobalAnalytics,

  getSingletonAnalytics,

} from '@lobehub/analytics';

// React hooks (separate import)

import {

  AnalyticsProvider,

  useAnalytics,

  useAnalyticsStrict,

  useEventTracking,

} from '@lobehub/analytics/react';

// Server-side analytics (includes posthog-node)

import { PostHogNodeAnalyticsProvider, createServerAnalytics } from '@lobehub/analytics/server';

```






[![][back-to-top]](#readme-top)






## 🚀 Quick Start



### Basic Usage



```typescript

import { createAnalytics } from '@lobehub/analytics';



// Configure analytics with business context

const analytics = createAnalytics({

  business: 'my-app', // Required: business name for SPM prefixing

  debug: process.env.NODE_ENV === 'development',

  providers: {

    posthog: {

      enabled: !!process.env.POSTHOG_KEY,

      key: process.env.POSTHOG_KEY!,

      host: process.env.POSTHOG_HOST, // optional

    },

  },

});



// Initialize

await analytics.initialize();



// Track events with automatic SPM prefixing

await analytics.trackEvent('user_signup', {

  method: 'email',

  source: 'landing_page',

  spm: 'homepage.cta', // Will become: 'my-app.homepage.cta'

});



// Identify users

await analytics.identify('user_123', {

  email: 'user@example.com',

  plan: 'pro',

});

```



### Global Instance Management



**Singleton Pattern (Recommended for simple apps):**



```typescript

import { createSingletonAnalytics, getSingletonAnalytics } from '@lobehub/analytics';



// Create singleton (usually in app initialization)

const analytics = createSingletonAnalytics({

  business: 'my-app',

  providers: {

    posthog: {

      enabled: true,

      key: process.env.POSTHOG_KEY!,

    },

  },

});



await analytics.initialize();



// Access from anywhere in your application

export function trackUserAction() {

  const analytics = getSingletonAnalytics();

  analytics.trackEvent('button_click', {

    button_name: 'signup',

    page: 'home',

  });

}

```



**Named Global Instances (For complex apps):**



```typescript

import { getGlobalAnalytics, setGlobalAnalytics } from '@lobehub/analytics';



// Register multiple instances

setGlobalAnalytics(mainAnalytics, 'main');

setGlobalAnalytics(adminAnalytics, 'admin');



// Use specific instances

getGlobalAnalytics('main').trackEvent('user_action', {});

getGlobalAnalytics('admin').trackEvent('admin_action', {});

```



### React Integration



**Enhanced AnalyticsProvider with auto-registration:**



```typescript

import React from 'react';

import { createAnalytics } from '@lobehub/analytics';

import {

  AnalyticsProvider,

  useAnalytics,

  useAnalyticsStrict

} from '@lobehub/analytics/react';



// Create analytics instance

const analytics = createAnalytics({

  business: 'my-app',

  providers: {

    posthog: {

      enabled: true,

      key: process.env.REACT_APP_POSTHOG_KEY!,

    },

  },

});



// Provider with auto-registration

function App() {

  return (

    

      

    

  );

}



// Use in components

function MyComponent() {

  const { analytics, isReady, isInitializing, error } = useAnalytics();



  // Safe usage with state checking

  if (isInitializing) return 
Loading analytics...
;

  if (error) return 
Analytics error: {error.message}
;

  if (!isReady) return 
Analytics not ready
;



  const handleClick = () => {

    analytics?.trackEvent('button_click', {

      button_name: 'cta',

      page: 'home',

    });

  };



  return Track Event;

}



// Strict mode (throws if not initialized)

function StrictComponent() {

  const analytics = useAnalyticsStrict(); // Throws if not ready



  const handleClick = () => {

    analytics.trackEvent('button_click', { button_name: 'strict-button' });

  };



  return Strict Track;

}

```



**Access analytics outside React components:**



```typescript

import { getGlobalAnalytics } from '@lobehub/analytics/react';



// In service functions, API handlers, etc.

export async function apiCall() {

  try {

    const response = await fetch('/api/data');



    // Track success

    const analytics = getGlobalAnalytics('main');

    analytics.trackEvent('api_call', {

      endpoint: '/api/data',

      success: true,

    });



    return response.json();

  } catch (error) {

    // Track error

    const analytics = getGlobalAnalytics('main');

    analytics.trackEvent('api_call', {

      endpoint: '/api/data',

      success: false,

      error: error.message,

    });

    throw error;

  }

}

```



### SPM (Source Page Medium) Auto-Prefixing



The library automatically handles SPM prefixing with your business name:



```typescript

const analytics = createAnalytics({

  business: 'my-app', // This will prefix all SPM values

  // ... other config

});



// These events will have SPM auto-prefixed:

analytics.trackEvent('button_click', {

  button_name: 'signup',

  spm: 'homepage.hero', // Becomes: 'my-app.homepage.hero'

});



analytics.trackEvent('page_view', {

  page: '/dashboard',

  spm: 'dashboard.main', // Becomes: 'my-app.dashboard.main'

});



// If no SPM provided, uses business name as default

analytics.trackEvent('user_login', {

  method: 'email',

  // spm will be: 'my-app'

});

```






[![][back-to-top]](#readme-top)






## 📖 API Reference



### Core Functions



#### `createAnalytics(config: AnalyticsConfig): AnalyticsManager`



Creates a configured analytics manager.



#### `AnalyticsManager`



Main class for managing analytics providers.



**Methods:**



- `initialize(): Promise` - Initialize all providers

- `track(event: AnalyticsEvent): Promise` - Track custom event

- `trackEvent(eventName: K, properties): Promise` - Track predefined event

- `identify(userId: string, properties?): Promise` - Identify user

- `trackPageView(page: string, properties?): Promise` - Track page view

- `reset(): Promise` - Reset user identity

- `setGlobalContext(context: EventContext): this` - Set global context

- `getStatus(): { initialized: boolean; providersCount: number }` - Get status



### Global Instance Management



#### Singleton Pattern



```typescript

// Create singleton

createSingletonAnalytics(config: AnalyticsConfig): AnalyticsManager



// Get singleton

getSingletonAnalytics(): AnalyticsManager

getSingletonAnalyticsOptional(): AnalyticsManager | null



// Check singleton

hasSingletonAnalytics(): boolean

resetSingletonAnalytics(): void // For testing

```



#### Named Global Instances



```typescript

// Register/unregister

setGlobalAnalytics(instance: AnalyticsManager, name?: string): void

removeGlobalAnalytics(name?: string): boolean

clearGlobalAnalytics(): void



// Access

getGlobalAnalytics(name?: string): AnalyticsManager

getGlobalAnalyticsOptional(name?: string): AnalyticsManager | null



// Utilities

hasGlobalAnalytics(name?: string): boolean

getGlobalAnalyticsNames(): string[]

```



### React Hooks & Provider



#### `AnalyticsProvider`



```typescript



  {children}



```



#### React Hooks



```typescript

// Safe access with state

useAnalytics(): {

  analytics: AnalyticsManager | null;

  isReady: boolean;

  isInitialized: boolean;

  isInitializing: boolean;

  error: Error | null;

}



// Strict access (throws if not ready)

useAnalyticsStrict(): AnalyticsManager



// State only

useAnalyticsState(): {

  isReady: boolean;

  isInitialized: boolean;

  isInitializing: boolean;

  error: Error | null;

}



// Optional access

useAnalyticsOptional(): AnalyticsManager | null



// Legacy hook (for backward compatibility)

useEventTracking(manager: AnalyticsManager): {

  trackButtonClick: (buttonName: string, properties?: any) => void;

  // ... other convenience methods

}

```



### Types



#### `AnalyticsConfig`



```typescript

interface AnalyticsConfig {

  business: string; // Required: business name for SPM prefixing

  debug?: boolean;

  providers: {

    posthog?: PostHogProviderAnalyticsConfig;

    umami?: UmamiProviderAnalyticsConfig;

    ga?: GoogleProviderAnalyticsConfig;

  };

}

```



#### `PostHogProviderAnalyticsConfig`



```typescript

interface PostHogProviderAnalyticsConfig {

  enabled: boolean;

  key: string;

  host?: string;

  debug?: boolean;

  // ... other PostHog config options

}

```



#### `PredefinedEvents`



```typescript

interface PredefinedEvents {

  // UI interactions

  button_click: {

    button_name: string;

    page?: string;

    section?: string;

    spm?: string;

    [key: string]: any;

  };



  // User actions

  user_signup: {

    method: 'email' | 'oauth' | 'phone';

    source?: string;

    spm?: string;

    [key: string]: any;

  };



  user_login: {

    method: 'email' | 'oauth' | 'phone';

    spm?: string;

    [key: string]: any;

  };



  // Chat interactions

  chat_message_sent: {

    message_length: number;

    model?: string;

    conversation_id?: string;

    spm?: string;

    [key: string]: any;

  };



  // Page tracking

  page_view: {

    page: string;

    referrer?: string;

    spm?: string;

    [key: string]: any;

  };



  // Form interactions

  form_submit: {

    form_name: string;

    success: boolean;

    spm?: string;

    [key: string]: any;

  };

}

```






[![][back-to-top]](#readme-top)






## 🛠️ Development



```bash

# Clone the repository

git clone https://github.com/lobehub/@lobehub/analytics.git

cd @lobehub/analytics



# Install dependencies

npm install



# Start development

npm run dev



# Build the library

npm run build



# Run tests

npm test



# Run examples

npm run example

```



### Project Structure



```

@lobehub/analytics/

├── src/

│   ├── base.ts           # Base analytics provider

│   ├── manager.ts        # Analytics manager

│   ├── config.ts         # Configuration factory

│   ├── global.ts         # Global instance management

│   ├── types.ts          # TypeScript definitions

│   ├── providers/        # Analytics providers

│   │   └── posthog.ts    # PostHog implementation

│   ├── react/            # React integration

│   │   ├── provider.tsx  # Enhanced Provider component

│   │   └── hooks.ts      # Legacy hooks

│   └── index.ts          # Main exports

├── examples/             # Usage examples

└── dist/                 # Built files (generated)

```






[![][back-to-top]](#readme-top)






## Examples



See the `examples/` directory for comprehensive usage examples:



- `examples/library-usage.ts` - Basic library usage and design principles

- `examples/enhanced-react-usage.tsx` - Advanced React integration

- `examples/singleton-enhanced-usage.ts` - Singleton pattern examples

- `examples/global-usage.ts` - Global instance management

- `examples/business-spm-example.ts` - SPM prefixing demonstration

- `examples/usage-summary.md` - Complete feature overview



## 🤝 Contributing



Contributions of all types are more than welcome, if you are interested in contributing code, feel free to check out our GitHub [Issues][github-issues-link] to get stuck in to show us what you're made of.



[![][pr-welcome-shield]][pr-welcome-link]



[![][github-contrib-shield]][github-contrib-link]






[![][back-to-top]](#readme-top)






---



#### 📝 License



Copyright © 2025 [LobeHub][profile-link]. 


This project is [MIT](./LICENSE) licensed.



[back-to-top]: https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square

[github-action-release-link]: https://github.com/lobehub/lobe-analytics/actions/workflows/release.yml

[github-action-release-shield]: https://img.shields.io/github/actions/workflow/status/lobehub/lobe-analytics/release.yml?label=release&labelColor=black&logo=githubactions&logoColor=white&style=flat-square

[github-action-test-link]: https://github.com/lobehub/lobe-analytics/actions/workflows/test.yml

[github-action-test-shield]: https://img.shields.io/github/actions/workflow/status/lobehub/lobe-analytics/test.yml?label=test&labelColor=black&logo=githubactions&logoColor=white&style=flat-square

[github-contrib-link]: https://github.com/lobehub/lobe-analytics/graphs/contributors

[github-contrib-shield]: https://contrib.rocks/image?repo=lobehub%2Flobe-analytics

[github-contributors-link]: https://github.com/lobehub/lobe-analytics/graphs/contributors

[github-contributors-shield]: https://img.shields.io/github/contributors/lobehub/lobe-analytics?color=c4f042&labelColor=black&style=flat-square

[github-forks-link]: https://github.com/lobehub/lobe-analytics/network/members

[github-forks-shield]: https://img.shields.io/github/forks/lobehub/lobe-analytics?color=8ae8ff&labelColor=black&style=flat-square

[github-issues-link]: https://github.com/lobehub/lobe-analytics/issues

[github-issues-shield]: https://img.shields.io/github/issues/lobehub/lobe-analytics?color=ff80eb&labelColor=black&style=flat-square

[github-license-link]: https://github.com/lobehub/lobe-analytics/blob/master/LICENSE

[github-license-shield]: https://img.shields.io/github/license/lobehub/lobe-analytics?color=white&labelColor=black&style=flat-square

[github-releasedate-link]: https://github.com/lobehub/lobe-analytics/releases

[github-releasedate-shield]: https://img.shields.io/github/release-date/lobehub/lobe-analytics?labelColor=black&style=flat-square

[github-stars-link]: https://github.com/lobehub/lobe-analytics/network/stargazers

[github-stars-shield]: https://img.shields.io/github/stars/lobehub/lobe-analytics?color=ffcb47&labelColor=black&style=flat-square

[npm-release-link]: https://www.npmjs.com/package/@lobehub/analytics

[npm-release-shield]: https://img.shields.io/npm/v/@lobehub/analytics?color=369eff&labelColor=black&logo=npm&logoColor=white&style=flat-square

[pr-welcome-link]: https://github.com/lobehub/lobe-analytics/pulls

[pr-welcome-shield]: https://img.shields.io/badge/%F0%9F%A4%AF%20PR%20WELCOME-%E2%86%92-ffcb47?labelColor=black&style=for-the-badge

[profile-link]: https://github.com/lobehub