JavaScript

The @faststats/web package is the core browser SDK. The React and Nuxt packages are built on top of it. Use it directly when you work with plain JavaScript, with a framework that has no dedicated package yet, or when you want full control over the lifecycle.

Install

 npm install @faststats/web

 pnpm add @faststats/web

 yarn add @faststats/web

 bun add @faststats/web

Start the Shared Client

Call init once from your application bootstrap. It creates and starts a shared client used by the package’s convenience functions.

import { init } from "@faststats/web";

export const analytics = init({
	siteKey: "your_site_key",
});

The core SDK records page views, page leaves, sessions, client-side navigation, and visit duration. Optional features are extensions, so they only add code to your bundle when you import them.

import { init } from "@faststats/web";
import { errorTracking } from "@faststats/web/error";
import { outboundLinks } from "@faststats/web/outbound-links";
import { sessionReplay } from "@faststats/web/replay";
import { webVitals } from "@faststats/web/web-vitals";

init({
	siteKey: "your_site_key",
	extensions: [outboundLinks(), errorTracking(), webVitals(), sessionReplay()],
});

Track Custom Events

The package exports functions that use the shared client. Calls made before init are ignored.

import { track } from "@faststats/web";

document.querySelector("#buy")?.addEventListener("click", () => {
	track("purchase", { plan: "pro", price: 29 });
});

Single Page Apps

The SDK patches pushState and replaceState and listens for popstate, so client side route changes are tracked as new page views with no extra work. If your router uses the hash for routing, turn on trackHash.

init({
	siteKey: "your_site_key",
	trackHash: true,
});

Manage an Independent Client

Use createClient when you need an isolated client—for example for multiple sites, tests, or a framework integration. Independent clients require an explicit start() call and are not used by the package-level convenience functions.

import { createClient } from "@faststats/web";

const analytics = createClient({ siteKey: "your_site_key" });
analytics.start();
analytics.track("purchase", { plan: "pro" });

// Remove listeners, flush active extensions, and stop tracking.
analytics.destroy();

You can also construct WebAnalytics directly. Like createClient, it does not start until you call start().

Shut Down the Shared Client

Call shutdown to destroy and forget the client created by init. A later call to init can then start a new shared client with different options.

import { shutdown } from "@faststats/web";

shutdown();