Configuration

React and JavaScript use the same core options. Pass them as props to React’s Analytics component or to JavaScript’s init, createClient, or WebAnalytics constructor. In Nuxt, place them under faststats.

Core OptionsCopy Anchor Link

The siteKey is public and safe to include in browser code. baseUrl applies to the core and all built-in extensions.

ExtensionsCopy Anchor Link

Error tracking, Web Vitals, and session replay are separate, tree-shakeable imports. Outbound link tracking is part of the core and needs no setup. With React or JavaScript, create each extension and add it to the extensions array.

Copy Text
import { Analytics } from "@faststats/react";
import { errorTracking } from "@faststats/react/error";
import { sessionReplay } from "@faststats/react/replay";
import { webVitals } from "@faststats/react/web-vitals";

<Analytics
	siteKey="your_site_key"
	extensions={[
		errorTracking(),
		webVitals(),
		sessionReplay({ recordConsole: true }),
	]}
/>;

Nuxt uses a serializable extensions object and loads the selected extensions for you.

Copy Text
export default defineNuxtConfig({
	modules: ["@faststats/nuxt"],
	faststats: {
		siteKey: "your_site_key",
		extensions: {
			errorTracking: true,
			webVitals: true,
			sessionReplay: { recordConsole: true },
		},
	},
});

Use true for default extension settings. errorTracking and sessionReplay also accept an options object; webVitals has no options. See Error Tracking, Web Vitals, and Session Replay for their options.

LifecycleCopy Anchor Link

init starts the JavaScript shared client immediately. createClient and the WebAnalytics constructor create independent clients that must be started explicitly.

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

const analytics = createClient({ siteKey: "your_site_key" });
analytics.start();

// Later, remove listeners and stop extensions.
analytics.destroy();

React and Nuxt own this lifecycle and start their clients automatically.

Custom ExtensionsCopy Anchor Link

An extension is an object with a name and a setup function. setup receives a context with the client’s settings and an on method for lifecycle hooks, and may return a cleanup function.

Copy Text
import type { AnalyticsExtension } from "@faststats/web";

export function diagnostics(): AnalyticsExtension {
	return {
		name: "diagnostics",
		setup(context) {
			context.on("pageChange", ({ url }) => {
				if (context.debug) console.debug("page changed", url);
			});

			return ({ discard }) => {
				// Flush buffered data, or drop it when `discard` is true.
			};
		},
	};
}

The context exposes siteKey, baseUrl, debug, trackHash, isCookieless(), getUserId(), and on(hook, handler). getUserId() returns the identified user, including one identified on an earlier page load.

Extensions start when tracking starts and stop when the client is destroyed or consent is denied. Cleanup receives discard: true when consent was revoked. Errors thrown from setup or a hook are caught and do not affect analytics.