Skip to content

Installation

The two SDK packages are distributed via npm. Both are ESM-only.

Browser SDK

Section titled “Browser SDK”
Terminal window
npm install @syntarie/tracking

Requires a bundler that resolves the exports field in package.json (Vite, esbuild, Rollup, Webpack 5, Parcel 2, Next.js, Remix, Astro — the modern default). The package has zero runtime dependencies in the browser bundle.

Node SDK

Section titled “Node SDK”
Terminal window
npm install @syntarie/tracking-node

Requires Node 20 or newer. ESM-only, single entry point.

Subpaths exposed by the browser SDK

Section titled “Subpaths exposed by the browser SDK”

Each subpath is its own bundle target so you only pay the gzip cost for what you actually import.

SubpathPurpose
@syntarie/trackingCore: init, track, identify, pageview, consent.
@syntarie/tracking/vitalsCore Web Vitals (LCP, FCP, CLS, INP, TTFB).
@syntarie/tracking/errorswindow.onerror + unhandled rejection capture.
@syntarie/tracking/clicksDelegated click capture, all-clicks or data-track mode.
@syntarie/tracking/scrollScroll-depth thresholds at 25 / 50 / 75 / 100 %.
@syntarie/tracking/engaged-timePer-pageview engaged-time accounting.
@syntarie/tracking/offline-queueIndexedDB-backed offline persistence.
@syntarie/tracking/retryLazy-loaded exponential-backoff retry orchestrator.
@syntarie/tracking/generated/eventsTyped track() overloads from your tracking plan.

The package is marked "sideEffects": false so any subpath you don’t import is tree-shaken entirely.

Bundle size budgets

Section titled “Bundle size budgets”
BundleTargetNotes
Core< 5 kB gzipEnforced in CI.
vitals< 1 kB gzip
errors< 1 kB gzip
clicks< 1 kB gzip
scroll< 1 kB gzip
engaged-time< 1 kB gzip
offline-queue≤ 1.5 kB gzip
retry≤ 1.5 kB gzip
generated/eventstree-shakes to zeroPure types — runtime is the same track.

Bundle budgets are enforced as deployment gates, not semver gates — see Versioning §1.5 for the policy.

Verifying the install

Section titled “Verifying the install”

After install, confirm your bundler resolves the package by importing the core:

import { init, track } from '@syntarie/tracking';
console.log(typeof init); // "function"

If your bundler reports an unresolved import, you are likely using a legacy toolchain that does not understand the exports field. Upgrade your bundler or pin to one of the listed modern defaults.

Next steps

Section titled “Next steps”