analytics

# Analytics A lightweight analytics abstraction layer for tracking page views, custom events, and identifying visitors. Designed to work with any third-party analytics tool or your own backend through a pluggable architecture. ## Features - Extendable plugin system for third-party integrations - Test and debug analytics with time travel and offline mode - Lifecycle hooks for modifying tracking calls - Isomorphic — works in browser and Node.js - Queues events until analytic libraries are loaded - Conditionally loads third-party scripts - Works offline - TypeScript support ## Installation ```bash npm install analytics --save ``` npx also available via yarn, pnpm, and bun. ## Usage ```js import Analytics from 'analytics' import googleAnalytics from '@analytics/google-analytics' import customerIo from '@analytics/customerio' const analytics = Analytics({ app: 'my-app-name', version: 100, plugins: [ googleAnalytics({ measurementIds: ['G-XXXXXXXX'] }), customerIo({ siteId: '123-xyz' }) ] }) analytics.page() analytics.track('userPurchase', { price: 20, item: 'pink socks' }) analytics.identify('user-id-xyz', { firstName: 'bill', lastName: 'murray' }) ``` ## Core API - `analytics.identify(userId, traits)` — Identify a visitor and set their data in localStorage - `analytics.track(eventName, payload)` — Track custom analytics events - `analytics.page(data)` — Trigger page view tracking - `analytics.user(key)` — Retrieve stored user data - `analytics.reset()` — Clear visitor information and reset state - `analytics.ready(callback)` — Fire when all providers have loaded - `analytics.on(event, callback)` / `analytics.once(event, callback)` — Listen to lifecycle events - `analytics.getState(key)` — Access sub-keys of internal state - `analytics.storage` — Utilities for persisting data (localStorage, cookies) - `analytics.plugins.enable/disable(namespace)` — Dynamically manage plugins ## Plugin System The library ships with many official plugins including Google Analytics, Segment, Amplitude, AWS Pinpoint, Countly, Crazy Egg, Churnzero, and activity-utils. Community plugins are also available. Custom plugins can be created to react to events or add custom methods. ## Philosophy - Never lock into a single analytics tool - Easy to add/remove providers by adjusting the plugins array - Respect visitor privacy and allow opt-out mechanisms - Pluggable API for business logic extensibility