Tracker

The tracker is a lightweight JavaScript library that collects page views, custom events, and Web Vitals from your site, and sends them to your yawa server.

Use a script tag

Your yawa server also serves the tracker as a static file, which lets you load it with a script tag:

<script type="module" src="https://your-yawa-server.com/static/yawa.js"></script>

This is the simplest option if your site doesn’t have a build step, or you’d rather not add a dependency. It works well for static site generators too. With Astro Starlight, for example, you can add it directly via the head config:

starlight({
  head: [
    {
      tag: "script",
      attrs: {
        type: "module",
        src: "https://your-yawa-server.com/static/yawa.js",
      },
    },
  ],
});

The script derives the server URL from where it was loaded, so no further configuration is needed.

Install as a package

If your project uses a bundler, add the tracker to your website or frontend app:

pnpm add yawa-tracker

npm install yawa-tracker

yarn add yawa-tracker

Setup

Initialize the lib once when your app loads:

import { init } from "yawa-tracker";

const cleanup = init({
  serverUrl: "https://your-yawa-server.com",
});

Options

Option	Required	Description
`serverUrl`	Yes	URL of your yawa server.
`webVitals`	No	Enable Web Vitals tracking. Defaults to `false`.

Custom events

To track a custom event, call track with a name and optional metadata:

import { track } from "yawa-tracker";

track({ name: "signup", metadata: { plan: "pro" } });

Keys and values must be strings, with a maximum of 10 keys and 200 characters per key/value.

Web Vitals

Core Web Vitals (CLS, FCP, INP, LCP, TTFB) can also be collected by enabling the option when initializing the tracker:

import { init } from "yawa-tracker";

const cleanup = init({
  serverUrl: "https://your-yawa-server.com",
  webVitals: true,
});

API

Function	Description
`init(options)`	Initialize the tracker. Returns a cleanup function.
`visit()`	Fire-and-forget page view tracking.
`visitAsync()`	Async page view tracking.
`track(data)`	Fire-and-forget custom event.
`trackAsync(data)`	Async custom event.