umami-analytics-next

A simple type-safe integration between the Umami Analytics API, loaded using Next's Script component.

Installation

npm install umami-analytics-next

Usage

import { umamiAnalyticsContextFactory } from "umami-analytics-next";


The package exposes a `umamiAnalyticsContextFactory` function that accepts a list of events to track (with the possibility of typing the event data), and returns the Providers and hooks for you to use.

const events = ["buy", "cancel", "gift", "sell", "signup", "view"] as const;
const { UmamiAnalyticsContext, UmamiAnalyticsProvider, useUmami } =
  umamiAnalyticsContextFactory(eventNames);

// Then, in your _app.tsx or layout component:
<UmamiAnalyticsProvider
  autoTrack={false} // defaults to true
  src="script-url"
  websiteId="website-id-provided-by-umami"
>
  {children}
</UmamiAnalyticsProvider>;

// and in any component that can consume this context:
const { track } = useUmami();
// Tracks a pageView - only needed if autoTrack is set to false
track();
// track has type-safe autocompletion for the event names
track("view");
track("buy", {
  amountItems: 3,
  couponCode: "C2024",
  success: true,
});

Advanced usage

Tracking events may require custom data associated to each event. The library allows to pass a generic TEventData type that allows to type the event data for each event. This way, the track function will be type-safe, and will autocomplete the event names and the event data.

import { umamiAnalyticsContextFactory } from 'umami-analytics-next'

const events = ['buy', 'cancel', 'gift', 'sell', 'signup', 'view'] as const

type Events = typeof events
type Event = Events[number]

// add a custom type for each custom event data you want to add type-safe
type SignUpEventData = {
  receiveUpdates: boolean
}
type OperationsEventData = {
  amountItems: number
  success: boolean
  couponCode?: string
}

type SignUpEvents = Extract<Event, 'signup'>
type OperationsEvents = Extract<Event, 'buy' | 'cancel' | 'gift' | 'sell'>

type AllEventsWithData = OperationsEvents | SignUpEvents

// Map each type with the corresponding event data
type EventDataMap = {
  [K in AllEventsWithData]: K extends SignUpEvents
    ? SignUpEventData
    : K extends OperationsEvents
      ? OperationsEventData
      : // be flexible with untyped events
        { [key: string]: unknown }
}

// Generic types are optional, but type-safety for event data will be missing if not provided
const { UmamiAnalyticsContext, UmamiAnalyticsProvider, useUmami } =
  umamiAnalyticsContextFactory<EventDataMap, Events>(
    eventNames,
  )

  // As above, in your _app.tsx or layout component:
  <UmamiAnalyticsProvider
    autoTrack={false} // defaults to true
    processUrl={removeLocaleAndTrailingSlash}
    src="script-url"
    websiteId="website-id-provided-by-umami"
  >
    {children}
  </UmamiAnalyticsProvider>

  // and in any component that can consume this context:
  const { track } = useUmami()
  // track has type-safe autocompletion in both the event name and the data
  // The event data is optional, but if provided, it must match the type of the event
  track('buy', {
    amountItems: 3,
    couponCode: 'C2024',
    success: true
  })
  track('signup', {
    receiveUpdates: true
  })

API

umamiAnalyticsContextFactory(events, options?)

Returns an object with UmamiAnalyticsContext, UmamiAnalyticsProvider, useUmami.

events

Type: string[]

The array of events. For type-safety, it must be a const assertion array.

UmamiAnalyticsProvider

The React provider. It accepts the following properties:

autoTrack?

Type: boolean Default: true

Whether to use the autotrack feature from Umami or not.

domains?

Type: string[] Default: undefined

A list of domains in which the tracker will run.

The properties accepted are:

processUrl?

Type: function Default: undefined

A function which receives the pathname and returns the processed URL. Useful for removing locale prefixes or trailing slashes.

src

Type: string

The URL of the script to load.

websiteId

Type: string

The umami website ID.

UmamiAnalyticsContext

The React context. It must be read with React's useContext. It reads all values given to the Provider, plus the value loaded

loaded

Type: boolean

Whether the script has been loaded or not.

useUmami

A custom hook which returns an object with the property track, which is undefined until loaded is true in the context

track

Type: function

It uses the same API as umami tracker functions, but with the type-safety from the event names and event data.