Error Tracking

Browser errors are reported by the web SDK. Server errors in Nitro routes are reported by @faststats/nitro.

Browser ErrorsCopy Anchor Link

Add the error-tracking extension to capture uncaught errors and unhandled promise rejections. The tracker batches them and drops noise from browser extensions automatically.

import { errorTracking } from "@faststats/react/error";

<Analytics siteKey="your_site_key" extensions={[errorTracking()]} />;

faststats: {
	siteKey: "your_site_key",
	extensions: { errorTracking: true },
}

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

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

Errors are grouped by their type and message so the same error from many visitors does not flood your dashboard. Identical errors within a batch are counted instead of repeated.

OptionsCopy Anchor Link

errorTracking({ flushInterval: 10_000, maxQueueSize: 100 });

In Nuxt, pass the same object as extensions.errorTracking.

Batches are also flushed when the page is hidden. If the collector is unreachable the queue is capped at maxQueueSize and the oldest errors are dropped. A batch the collector rejects is not retried.

Report Errors by HandCopy Anchor Link

When you catch an error yourself, send it through the running client. An error-tracking extension must be active to receive the report.

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

try {
	doRiskyThing();
} catch (error) {
	reportError(error as Error);
}

In React, get the client with useAnalytics() and call analytics?.reportError(error). In Nuxt, call $faststats.reportError(error).

In Nuxt, enabling extensions.errorTracking also hooks the module into the Vue error handler, so component errors are reported without extra code.

Server Errors with NitroCopy Anchor Link

If you run Nitro, either standalone or through Nuxt, you can report errors thrown in server routes with @faststats/nitro. The package ships a plugin for Nitro v2 and one for Nitro v3.

npm install @faststats/nitro

import { createRequire } from "node:module";

const require = createRequire(import.meta.url);
const errorTrackingPlugin = require.resolve("@faststats/nitro/v2");

export default defineNuxtConfig({
	nitro: {
		plugins: [errorTrackingPlugin],
	},
});

export default defineNitroConfig({
	plugins: ["@faststats/nitro/v2"],
});

Use the /v3 import instead when you are on Nitro v3.

Server ConfigurationCopy Anchor Link

The server plugin reads its settings from environment variables. The token is a project token, not the browser site key, so keep it on the server only.

FASTSTATS_TOKEN=your_project_token

If FASTSTATS_TOKEN is not set the plugin stays silent and skips reporting, so it is safe to leave installed in environments without a token.

Custom ConfigurationCopy Anchor Link

You can also create a plugin with explicit options instead of environment variables. This lets you attach extra context to every error.

import { createFaststatsNitroPluginV2 } from "@faststats/nitro/v2";

export default createFaststatsNitroPluginV2({
	token: process.env.FASTSTATS_TOKEN,
	getContext: ({ path }) => ({ route: path }),
});

getContext receives the error, the request path, and Nitro’s error tags. Use createFaststatsNitroPluginV3 from @faststats/nitro/v3 on Nitro v3.

The reporter batches errors, retries failed sends and opens a short circuit breaker after repeated failures so a broken endpoint never slows your server down.