Install with npm

Use the npm package when your site is an app with a bundler (Next.js, Vite, webpack…). The tracker is then part of your code, typed, and needs no extra script tag.

npm install @sublim_analytics/tracker

The package ships ES modules, CommonJS and TypeScript definitions. It has no runtime dependencies.

Usage

Call init() once, as early as possible on the client, then use the other functions anywhere:

JavaScript

import { init, trackEvent } from '@sublim_analytics/tracker';

init({ projectId: 'YOUR_PROJECT_ID' });

trackEvent('signup', { props: { plan: 'pro' } });

No side effects on import. Nothing happens until init() is called.
SSR-safe. On the server (no window), init() and the tracking functions do nothing.
Calls before init() are queued. Up to 100 calls are kept and sent once tracking starts.
One instance per page. A second init() logs a warning and is ignored. If the CDN snippet is also on the page, both share a single instance and nothing is counted twice.

Exports

Export	Description
`init(options?)`	Starts tracking. Takes the configuration options.
`trackEvent(name, options?)`	Sends a custom event.
`trackPageview(options?)`	Sends a pageview manually. Rarely needed: navigations are tracked automatically.
`trackPurchase(options?)`	Sends a `purchase` event with its revenue.
`isInitialized()`	Whether this page is being tracked, by this package or by the CDN snippet.

The package also exposes window.sublim after init(), so code that uses the global, like a tag manager or another script, keeps working.

Framework setup

Where to call init() depends on your framework. Your choice is remembered on the other pages of this documentation.

App Router: create a client component that initialises the tracker, and render it once in the root layout.

JSX

// app/sublim-analytics.jsx
'use client';

import { useEffect } from 'react';
import { init } from '@sublim_analytics/tracker';

export function SublimAnalytics() {
  useEffect(() => {
    init({ projectId: process.env.NEXT_PUBLIC_SUBLIM_PROJECT_ID });
  }, []);
  return null;
}

JSX

// app/layout.jsx
import { SublimAnalytics } from './sublim-analytics';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <SublimAnalytics />
        {children}
      </body>
    </html>
  );
}

Pages Router: call init() in a useEffect of pages/_app.jsx.

Client-side navigations are tracked automatically; you don't need to call trackPageview on route changes.

Session replay without the CDN

By default, session replay loads its recorder (rrweb) from cdn.sublimanalytics.com when a recording starts. To bundle it instead, for example under a strict Content Security Policy, pass it through the replay option. It is loaded lazily, in its own chunk:

JavaScript

import { init } from '@sublim_analytics/tracker';

init({
  projectId: 'YOUR_PROJECT_ID',
  replay: () => import('@sublim_analytics/tracker/replay'),
});

The replay entry is about 180 KB minified, which is why it is not part of the main import. See Session replay.

TypeScript

Types are included. The main ones:

TypeScript

import type {
  SublimOptions,
  TrackEventOptions,
  TrackPageviewOptions,
  TrackPurchaseOptions,
} from '@sublim_analytics/tracker';