Vercel Analytics

@vercel/analytics is Vercel’s official client SDK for Web Analytics, a privacy-friendly, real-time traffic-insights product built into the Vercel platform. It automatically tracks page views once injected and exposes a small track() API for custom events, with dedicated entry points for Next.js, React, Vue, Nuxt, Remix, SvelteKit, and Astro so each framework gets an idiomatic integration instead of a generic script tag.

Because the package ships no analytics logic of its own beyond event shaping, it stays extremely small: it loads a hosted collector script in the browser (or logs to the console in development) and, for server-side events, POSTs directly to Vercel’s /_vercel/insights/event endpoint using request context pulled from headers or Vercel’s internal async storage. This makes it a thin, dependency-free wrapper around a single external service rather than a general-purpose analytics library.

What You Get

• A framework-specific <Analytics /> component (React/Next.js) or plugin/module (Vue, Nuxt, SvelteKit, Remix, Astro) that injects the tracking script and wires up automatic page-view tracking
• A track(name, properties) function for custom client-side events, with property validation that strips or rejects nested objects to keep payloads flat
• A separate @vercel/analytics/server entry point for server-side event tracking that reads request headers or Vercel’s request context automatically
• Automatic development/production mode detection, so events log to the console locally instead of hitting the real collector
• A beforeSend middleware hook to redact or cancel events before they leave the browser, plus support for self-hosted DSNs and custom endpoints

Common Use Cases

• Dropping <Analytics /> into a Next.js layout.tsx to get automatic page-view tracking on every route with zero extra config
• Firing custom events like track('Signup Completed') from a checkout or onboarding flow to measure conversion
• Tracking server-rendered actions (e.g. a form submission handled entirely in a server action) with track() from @vercel/analytics/server
• Redacting sensitive query parameters or user identifiers from outgoing events via a beforeSend callback before they reach Vercel

Under The Hood

Architecture: The package centers on a shared core (generic.ts, utils.ts, queue.ts) that every framework adapter re-exports through a thin wrapper. queue.ts establishes window.va/window.vaq so events can be queued before the collector script finishes loading; inject() in generic.ts builds the script tag (pointing at Vercel’s hosted collector, or a script.debug.js build in development) and attaches config as data-* attributes, while track() and pageview() push events through window.va. The React/Next <Analytics /> component and its Vue/Nuxt/SvelteKit/Remix/Astro counterparts all just call inject() on mount with framework metadata attached. server/index.ts is architecturally separate: it has no browser dependency and instead POSTs directly to /_vercel/insights/event, resolving request context from an explicit headers/request argument or from Vercel’s internal Symbol.for('@vercel/request-context') async-storage hook.

Tech Stack: Pure TypeScript with zero required runtime dependencies — react, vue, svelte, next, nuxt, @sveltejs/kit, and @remix-run/react are all optional peer dependencies, so the base install stays framework-agnostic. Framework-specific code is split into subpath exports (./react, ./next, ./vue, ./nuxt, ./nuxt/runtime, ./remix, ./sveltekit, ./astro, ./server), each built by tsup into matching ESM/CJS bundles with per-path .d.ts files declared via typesVersions. The Nuxt integration uses @nuxt/kit for module registration; tests run on Vitest with @testing-library/react for the React adapter.

Code Quality: Nearly every module has a co-located *.test.ts file — generic.test.ts, utils.test.ts (450 lines), a 594-line server/index.test.ts, and per-framework utils.test.ts files for React, Vue, Remix, and SvelteKit — covering edge cases like property stripping, route-to-pattern computation, and header parsing across ~2,560 lines of src. Error handling consistently favors soft failure (console warnings) in production while throwing clear, actionable errors in development, e.g. explicitly telling a developer they imported the client track() in a server context.

API Design: The public surface (inject/track/pageview, exposed as <Analytics /> in framework adapters) stays nearly identical across every supported framework, so switching from Next.js to Remix or SvelteKit requires no relearning. Configuration props (mode, debug, beforeSend, dsn, disableAutoTrack) are minimal with sensible auto-detected defaults, and the deliberate split between @vercel/analytics (client) and @vercel/analytics/server (server) — enforced with a descriptive runtime error on misuse — is a good piece of friction against a common mistake, at the cost of two same-named functions living at different import paths.