Dub Analytics

@dub/analytics is the official client-side SDK for Dub, the link management and attribution platform. It injects a lightweight tracking script into your app to capture link clicks, site visits, and outbound link traversals, then exposes helpers for recording lead and sale conversion events tied back to the originating click.

The package ships both a framework-agnostic inject() function and a ready-made React <Analytics /> component plus a useAnalytics() hook, so teams running Next.js, plain HTML, or a custom framework can wire up first-click or last-click attribution, configurable tracking cookies, and cross-domain outbound tracking without hand-rolling a script loader.

What You Get

• A universal inject() function that loads Dub’s tracking script into any framework
• A React <Analytics /> component and useAnalytics() hook for Next.js and other React apps
• Configurable first-click or last-click attribution models
• Built-in cookie configuration for tracking window, domain, and SameSite behavior
• Cross-domain outbound link tracking via domainsConfig.outbound

Common Use Cases

• Tracking referral and affiliate link clicks across a SaaS product
• Recording lead and sale conversion events for a partner or affiliate program
• Measuring site-visit traffic driven by a Dub short link
• Passing partner and discount metadata into checkout flows via useAnalytics()

Under The Hood

Architecture The SDK is intentionally thin: src/generic.ts’s inject() builds a window-global command queue (the classic async script-loader pattern used by tools like ga.js and fbq), then appends a <script> tag whose filename is built from enabled features (site-visit, outbound-domains, conversion-tracking) and whose data-* attributes carry the caller’s config to Dub’s externally hosted tracking script. src/react.tsx wraps inject() in a useEffect, while src/use-analytics.ts layers a stateful hook on top that listens for a ready event from the injected script and exposes trackClick/trackLead/trackSale proxies plus partner and discount state read off window.DubAnalytics. src/types.ts centralizes the public prop and event shapes consumed by both entry points. The actual attribution, cookie persistence, and event batching logic lives in the externally hosted script, not in this package — its job is purely to construct the right URL/attributes and expose a typed surface over the global queue.

Tech Stack Written in TypeScript and built with tsup (via @swc/core) into dual ESM/CJS bundles with two entry points — a generic bundle from generic.ts and a React-only bundle from react.tsx that gets a "use client" banner injected for RSC compatibility. The package lives inside a pnpm workspace monorepo alongside example apps (plain HTML, Next.js, a Next.js reverse-proxy variant, and a geolocation-script variant) that double as integration fixtures, plus a shared @dub/eslint-config and Husky/lint-staged/Prettier tooling enforced at the workspace root. server-only is a declared dependency, guarding against the client entry point being pulled into a server context.

Code Quality No unit tests exist inside packages/web itself, but the sibling apps/nextjs example ships Playwright end-to-end specs (track-click, track-visit, outbound-domains, analytics-config) that exercise the SDK’s real behavior in a browser. Types are extensively documented with JSDoc in types.ts, naming is consistent, and the workspace shares a single ESLint config with pre-commit linting via Husky. Error handling is minimal by design — a failed script load only logs to the console rather than throwing — appropriate for a non-critical analytics script.

API Design The public surface favors minimal boilerplate: a single <Analytics /> component with sensible defaults gets tracking running, and useAnalytics() exposes partner/discount state plus tracking methods with no extra setup. Deprecated options (shortDomain, queryParam) are kept working alongside their replacements (domainsConfig.refer, queryParams), and every prop carries inline JSDoc with defaults and examples, keeping the README and editor tooltips in sync.