@statvisor/sdk
Official SDK for Statvisor — backend API monitoring and frontend performance analytics. Fast, resilient, and built for Node, Next.js, and edge/serverless runtimes. Zero-config batching, automatic retries, and non-blocking delivery so it never adds latency to your responses.
Installation
npm install @statvisor/sdkBackend monitoring
Create one Statvisor client and attach the adapter for your framework.
import { Statvisor } from "@statvisor/sdk";
const sv = new Statvisor({ apiKey: process.env.STATVISOR_API_KEY! });Express
app.use(sv.express());Fastify
await fastify.register(sv.fastify());Next.js (App Router) — wrap every handler in a route file at once:
// lib/statvisor.ts
import { Statvisor } from "@statvisor/sdk";
export const sv = new Statvisor({ apiKey: process.env.STATVISOR_API_KEY! });
// app/api/users/route.ts
import { NextResponse } from "next/server";
import { sv } from "@/lib/statvisor";
export const { GET, POST } = sv.route("/api/users", {
GET: async () => NextResponse.json({ users: [] }),
POST: async () => NextResponse.json({}, { status: 201 }),
});Delivery is scheduled with Next's after(), so the ingest request runs after your
response is sent — zero added latency.
Hono / edge
app.use("*", sv.hono());Cloudflare Workers — uses ctx.waitUntil automatically:
export default { fetch: sv.wrapFetch(async (request, env, ctx) => new Response("ok")) };Structured logs
sv.log("error", "Payment failed", { userId, amount });
// or, using the last-created client:
import { log } from "@statvisor/sdk";
log("warn", "Retry triggered", { attempt: 3 });Options
| Option | Default | Description |
|---|---|---|
apiKey |
— | Project API key (required). |
environment |
process.env.NODE_ENV || "production" |
Tag attached to every event. |
sampleRate |
1 |
Keep this fraction of events (0–1). |
flushInterval |
5000 |
Timer flush interval (ms) in long-lived runtimes. |
batchSize |
50 |
Auto-flush once this many events are buffered. |
maxQueueSize |
1000 |
Hard cap; oldest events drop past this. |
timeoutMs |
5000 |
Per-request network timeout. |
maxRetries |
3 |
Retries on 429/5xx/network (exponential backoff, honors Retry-After). |
ignoreRoutes |
[] |
Skip routes by exact match or prefix. |
normalizeRoute |
id masking | Rewrite raw routes to low-cardinality templates. |
beforeSend |
— | Inspect / rewrite / drop each event (return null to drop). |
Frontend analytics
// app/layout.tsx
import { StatvisorAnalytics } from "@statvisor/sdk/react";
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<StatvisorAnalytics frontendKey="vl_fe_..." />
</body>
</html>
);
}Tracks page views, SPA route changes, session duration, and Core Web Vitals (LCP, CLS, INP,
FCP, TTFB) using Google's web-vitals library.
Delivery uses sendBeacon with a CORS-safelisted body so cross-origin events are never dropped.
GDPR consent banner
import { StatvisorConsentBanner } from "@statvisor/sdk/consent";
<StatvisorConsentBanner frontendKey="vl_fe_..." />Or control consent yourself:
import { grantConsent, revokeConsent, hasConsent } from "@statvisor/sdk/browser";Full guides at statvisor.com/docs.
Migrating from 0.x
The backend API is now a single client instead of standalone functions:
- import * as statvisor from "@statvisor/sdk";
- app.use(statvisor.express({ apiKey }));
- const { route } = statvisor.nextjs({ apiKey });
- export const { GET } = route("/api/users", { GET });
- statvisor.log("info", "hi");
+ import { Statvisor } from "@statvisor/sdk";
+ const sv = new Statvisor({ apiKey });
+ app.use(sv.express());
+ export const { GET } = sv.route("/api/users", { GET });
+ sv.log("info", "hi");createMiddleware(opts) → sv.hono(), and wrapFetch(opts, handler) → sv.wrapFetch(handler).
The frontend API is unchanged: initStatvisor, <StatvisorAnalytics>,
<StatvisorConsentBanner>, and the consent helpers keep the same signatures.
License
MIT