Analytics Library

A framework-agnostic analytics library for frontend applications, built on top of analytics.js (docs & source). Supports multiple analytics backends (Faro, and anything supported by analytics.js plugins) with a unified .track() API.

Note: This library uses analytics.js under the hood, so you can use any analytics provider for which an analytics.js plugin exists (e.g., Google Analytics, Segment, PostHog, etc.), in addition to the built-in Faro plugin. For full API and plugin documentation, see the analytics.js GitHub repo.

Installation

pnpm add @aleph-alpha/lib-analytics
# or
npm install @aleph-alpha/lib-analytics
# or
yarn add @aleph-alpha/lib-analytics

Usage

Basic Setup (Vue Example)

import { AnalyticsVuePlugin, useAnalytics, FaroAnalyticsPlugin } from '@aleph-alpha/lib-analytics';

// Configure your analytics plugins (e.g., Faro, or any analytics.js plugin)
const faroPlugin = FaroAnalyticsPlugin({
  url: 'https://your-faro-instance.com/collect',
  enabled: true,
  apiKey: 'AATOKEN', // optional, if your Faro instance requires it
});

// You can also use any analytics.js plugin, e.g.:
// import googleAnalytics from 'analytics-plugin-google-analytics';
// const gaPlugin = googleAnalytics({ trackingId: 'UA-...' });

// In your main.ts
import { createApp } from 'vue';
import App from './App.vue';

const app = createApp(App);
app.use(AnalyticsVuePlugin, {
  plugins: [faroPlugin /*, gaPlugin, ... */],
  app: 'MyApp',
  version: '1.0.0',
  debug: true, // optional
});
app.mount('#app');

// In a component or composable
import { useAnalytics } from '@aleph-alpha/lib-analytics';

const analytics = useAnalytics();
analytics.track('user_login', { user_id: '123' });
analytics.page({ url: '/dashboard' });
// Identify with just an ID (recommended minimal)
analytics.identify('123');

// Identify with ID and optional fields (email, username, fullName, roles, attributes)
analytics.identify('123', {
  email: '[email protected]',
  username: 'johndoe',
  fullName: 'John Doe',
  roles: 'admin',
  attributes: { plan: 'premium', signupDate: '2025-08-21' }, // values must be strings
});

Usage Without Vue (Plain TypeScript/JavaScript)

You can use this library in any JavaScript or TypeScript project, not just Vue apps. Just call initAnalytics directly and use the returned instance (or the exported analytics proxy):

import { initAnalytics, analytics, FaroAnalyticsPlugin } from '@aleph-alpha/lib-analytics';

const faroPlugin = FaroAnalyticsPlugin({
  url: 'https://your-faro-instance.com/collect',
  enabled: true,
});

// Initialize analytics (call this once at app startup)
const analyticsInstance = initAnalytics({
  plugins: [faroPlugin],
  app: 'MyApp',
  version: '1.0.0',
  debug: true,
});

// Use the analytics instance directly
analyticsInstance.track('user_signup', { plan: 'pro' });
analyticsInstance.page({ url: '/signup' });

// Or use the exported proxy (always points to the latest instance)
analytics.track('user_signup', { plan: 'pro' });

Local Development & Live-Reloading

If you want to test changes to this package in a local app and see updates instantly as you develop, use pnpm link and tsup --watch:

1. In the package directory:

   pnpm run dev

   This will keep your dist/ up to date as you edit.

2. Link the package globally:

   pnpm link --global

3. In your app directory:

   pnpm remove @aleph-alpha/lib-analytics   # (optional, but recommended)
   pnpm link --global @aleph-alpha/lib-analytics

   This creates a symlink in your app’s node_modules pointing to your local package.

4. Use the package in your app as usual:

   import { AnalyticsVuePlugin } from '@aleph-alpha/lib-analytics';

5. Edit, save, and see changes:

   • As you edit your package, tsup --watch rebuilds the output.
   • Your app immediately uses the new code (no need to reinstall or relink).
   • Just refresh/restart your app’s dev server if needed.

6. To unlink when done:

   pnpm unlink --global @aleph-alpha/lib-analytics
   pnpm install

Configuration

• Faro Plugin:

  • url: Faro backend URL (required)
  • enabled: Enable or disable the plugin (required)
  • apiKey: Faro API key (optional)

• Other analytics.js plugins:

  • You can use any plugin supported by analytics.js. See the analytics.js plugin directory for more options.

Example:

import { FaroAnalyticsPlugin } from '@aleph-alpha/lib-analytics';
// import googleAnalytics from 'analytics-plugin-google-analytics';

const faroPlugin = FaroAnalyticsPlugin({
  url: 'https://your-faro-instance.com/collect',
  enabled: true,
  apiKey: 'AATOKEN',
});
// const gaPlugin = googleAnalytics({ trackingId: 'UA-...' });

API Reference

AnalyticsVuePlugin

• Vue plugin for providing analytics via plugins (analytics.js-based).
• Usage: app.use(AnalyticsVuePlugin, { plugins: [...] })

useAnalytics

• Vue composable to access the analytics.js API in components.
• Usage: const analytics = useAnalytics();
• Methods:
  • track(event: string, properties?: object): Track a custom event
  • page(meta?: object): Set page metadata
  • identify(user: object): Set user context
  • ...and all other analytics.js API methods

initAnalytics / analytics (plain usage)

• initAnalytics(config) initializes analytics.js with your plugins and config.
• analytics is a proxy that always points to the latest analytics instance.
• Usage:

  import { initAnalytics, analytics } from '@aleph-alpha/lib-analytics';
  initAnalytics({ plugins: [...] });
  analytics.track('event', { ... });

FaroAnalyticsPlugin

• analytics.js plugin for Grafana Faro.
• Usage: FaroAnalyticsPlugin({ url, enabled, apiKey })

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.