@amplitude/analytics-browser

@amplitude/analytics-browser is Amplitude’s official TypeScript SDK for tracking product-analytics events from browser-based applications. It ships as both an npm package and a drop-in script-loader snippet, and wraps event queuing, session management, device/user identity, and network transport behind a small init()/track() API so teams can start sending events with a few lines of code.

Beyond manual event tracking, the SDK bundles a set of first-party autocapture plugins for page views, form interactions, file downloads, network requests, web vitals, and DOM “frustration” signals (rage clicks, dead clicks), plus attribution tracking for marketing campaign parameters and page-URL/custom event enrichment. These are wired in through @amplitude/analytics-core’s plugin architecture and can be toggled granularly via the autocapture config option.

The package is one piece of the larger amplitude/Amplitude-TypeScript pnpm/Nx monorepo, which also publishes @amplitude/analytics-node, @amplitude/analytics-react-native, and companion plugins like @amplitude/plugin-session-replay-browser. analytics-browser depends on several of these workspace plugins directly, so installing it pulls in a curated default tracking stack rather than a bare event pipe.

It supports remote config fetching (to adjust tracking behavior without a redeploy), configurable server zones (US/EU data residency), pluggable transports, and diagnostics sampling — features aimed at teams running Amplitude at production scale rather than a toy tracking script.

What You Get

• Core tracking API - init, track, identify, groupIdentify, revenue, and setUserId/setDeviceId for manual event and identity instrumentation.
• Built-in autocapture plugins - page view tracking, form interaction tracking, file download tracking, network capture, web vitals, and frustration-interaction (rage/dead click) detection enabled by default and individually configurable.
• Web attribution tracking - automatic capture of UTM parameters, click IDs, and referrer data to tie events back to marketing campaigns.
• Remote config support - fetches tracking configuration from Amplitude’s servers at init time so behavior can be adjusted without a client redeploy.
• Script-loader distribution - a minified CDN snippet with a queuing shim, so pages can start tracking before the full SDK has loaded.
• Server-zone and transport configuration - explicit US/EU server zone selection and a pluggable transport layer (fetch, XHR, beacon) for network delivery.
• Session Replay integration point - designed to compose with @amplitude/plugin-session-replay-browser from the same monorepo for recording user sessions alongside events.

Common Use Cases

• Product analytics instrumentation - a SaaS team adds amplitude.init() plus amplitude.track() calls to measure feature adoption and funnels.
• Marketing attribution - a growth team relies on the built-in web-attribution plugin to connect ad-campaign UTM parameters to downstream conversion events.
• Passive UX signal capture - a product team enables frustration-interaction tracking to surface rage clicks and dead clicks without hand-instrumenting every button.
• Regulated data residency - an EU-based company sets serverZone: 'EU' so all analytics traffic is processed in Amplitude’s EU infrastructure.
• Legacy-page instrumentation - a marketing site with no build step uses the CDN script-loader snippet to start tracking without an npm install.

Under The Hood

Architecture The package composes a monolithic AmplitudeBrowser client (extending AmplitudeCore from the shared @amplitude/analytics-core package) with a set of independently-published plugin packages injected as constructor-time dependencies rather than imported ad hoc. init() in browser-client.ts walks through a staged sequence — resolve logger and server zone, optionally fetch remote config via RemoteConfigClient, build a BrowserConfig, construct a Destination/transport pipeline, then conditionally register each autocapture plugin (page views, forms, file downloads, network capture, web vitals, frustration signals, attribution, enrichment) based on resolved AutocaptureOptions. Public exports in index.ts are destructured off a lazily-created singleton client via browser-client-factory.ts, and a parallel snippet-index.ts/generated/ build produces the CDN script-loader bundle with its own queuing shim. Changing the core plugin-registration contract in AmplitudeCore would ripple through every first-party plugin package in the monorepo, since they all implement the same plugin interface.

Tech Stack Written entirely in TypeScript, built with Rollup (rollup.config.js) for the browser/CDN bundle and tsc for separate ES5 and ESM output targets, inside an Nx + Lerna + pnpm-workspaces monorepo (amplitude/Amplitude-TypeScript) that also builds @amplitude/analytics-node, @amplitude/analytics-react-native, and a family of plugin-*-browser packages consumed here as workspace dependencies. Runtime dependencies are limited to tslib plus sibling workspace plugin packages — no external analytics or HTTP libraries are pulled in, keeping the shipped bundle lean.

Code Quality Testing uses Jest with jest-environment-jsdom and a shared root config extended per-package; the test/ directory mirrors src/ closely (browser-client.test.ts, config.test.ts, default-tracking.test.ts, per-plugin test folders) and coverage-path ignores are scoped narrowly to snippet/global-scope glue code, suggesting deliberate coverage tracking rather than blanket exclusion. ESLint + Prettier run via pnpm lint/fix scripts, ts-strict typing is used throughout (explicit @ts-ignore comments are annotated with reasons where used), and Playwright end-to-end tests plus a dedicated ci.yml/ci-nx.yml/e2e.yml GitHub Actions pipeline cover build, lint, unit, and browser e2e stages.

API Design The public surface is intentionally small — init, track, identify, groupIdentify, revenue, plus getter/setter pairs for device/user/session IDs — with sensible defaults so most integrations need only an API key. Autocapture is opt-out rather than opt-in (enabled by default, individually disable-able via a typed AutocaptureOptions object), which minimizes required configuration for common analytics needs while still exposing granular control for teams that want it. Backward-compatible type re-exports (export * as Types) and a documented, commented rationale in index.ts show attentiveness to not breaking downstream consumers across versions.