react-tracking

react-tracking is a React-specific library from The New York Times for adding analytics tracking to applications in a declarative way. It lets you attach tracking data to individual components using a track() higher-order component or decorator, or the useTracking hook, so tracking concerns stay compartmentalized instead of leaking across the app.

Tracking data defined on parent components is merged into child events through React context, giving every dispatched event the accumulated context of the component tree. The library is analytics-platform agnostic — you supply a dispatch function — and supports both declarative and imperative event tracking, making it a clean foundation for instrumenting user behavior.

What You Get

• A track() API usable as a decorator, HOC, or wrapper for class and function components
• A useTracking hook for tracking in function components
• Context-based merging of tracking data down the component tree
• Both declarative (data props) and imperative (trackEvent) tracking
• A pluggable dispatch function, keeping the library analytics-platform agnostic

Common Use Cases

• Instrumenting user interactions and page views in a React app
• Colocating tracking metadata with the components that emit events
• Sending events to any analytics backend via a custom dispatch function
• Building up hierarchical event context from parent to child components

Under The Hood

Architecture — The core is a React context (ReactTrackingContext.js) that carries a tracking dispatch function and accumulated data down the tree. useTrackingImpl.js reads the parent context, deepmerges the component’s own tracking data, and exposes trackEvent plus a Provider for children; useTracking.js and the decorator/HOC layer (trackingHoC.js, withTrackingComponentDecorator.js, trackEventMethodDecorator.js, makeClassMemberDecorator.js) are thin wrappers over that hook so class and function components share one implementation. dispatchTrackingEvent.js is the default dispatcher.

Tech Stack — JavaScript React library with two small runtime dependencies — deepmerge for combining context data and hoist-non-react-statics for the HOC — plus peer dependencies on react and prop-types.

Code Quality — A tests directory covers the hook, decorators, HOC, and context propagation. The design deliberately funnels every public entry point through useTrackingImpl, minimizing duplicated logic between the decorator and hook APIs.

API Design — The single track()/useTracking() abstraction reads declaratively (pass data) while still allowing imperative trackEvent calls, and being dispatch-agnostic means teams bind it to any analytics backend. Supporting decorator, HOC, and hook forms makes it adoptable in both legacy and modern React codebases.