Registry / observability / react-tracking

react-tracking

JSON →
library9.3.2jsnpmunverified

react-tracking is a declarative and imperative tracking library specifically designed for React applications. It provides an analytics platform-agnostic solution, empowering developers to manage and dispatch user interaction data effectively. The library's core philosophy is to compartmentalize tracking concerns directly within individual components, thereby preventing data leakage and ensuring a clean separation of concerns across the entire application. It offers a dual API approach, supporting both the traditional Higher-Order Component (HoC) or decorator pattern and a modern React Hooks API, which was fully introduced in version 8.1.0 for functional components. The current stable version, 9.3.2, has recently addressed compatibility issues with React Native environments and re-enabled support for Node.js 16.9+. Developed by The New York Times, react-tracking is actively maintained, with a consistent cadence of patch and minor releases addressing bug fixes and introducing new features like `mergeOptions` (v9.3.0) and `deepmerge` re-export (v9.2.0). Its key differentiators include its highly declarative nature, flexibility to integrate seamlessly with virtually any analytics backend, and comprehensive support for both class-based and modern functional React components, making it a versatile choice for instrumenting React UIs.

npm install react-tracking
INSTALL
IMPORT
SIG · REACT-TRACKING
R
react-tracking
observabilityjavascriptv9.3.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

track
import track from 'react-tracking';
import { track } from 'react-tracking';
`track` is the default export, primarily used for the Higher-Order Component (HoC) or decorator pattern with class components.
useTracking
import { useTracking } from 'react-tracking';
const { useTracking } = require('react-tracking');
A named export for the React Hooks API, introduced in v8.1.0, for use with functional components. ESM-only usage is preferred.
Track
import { Track } from 'react-tracking';
import { track } from 'react-tracking';
`Track` is a component returned by the `useTracking` hook, used to explicitly wrap JSX and pass contextual tracking data to child components.
deepmerge
import { deepmerge } from 'react-tracking';
import deepmerge from 'deepmerge';
Re-exported for convenience since v9.2.0, useful when providing custom `mergeOptions` or needing deep merging capabilities with tracking data.

Demonstrates how to use the `useTracking` hook to declare component-level tracking data, imperatively dispatch events with `trackEvent`, access contextual data with `getTrackingData`, and use the `<Track>` component to propagate context to child components. It also shows options like `dispatchOnMount` and `mergeOptions`.

import React, { useEffect } from 'react'; import { useTracking, Track } from 'react-tracking'; interface MyComponentProps { userId: string; pageName: string; } const ProductPage: React.FC<MyComponentProps> = ({ userId, pageName }) => { // Initialize tracking for this component, passing contextual data const { Track, trackEvent, getTrackingData } = useTracking( { page: pageName, user: userId, environment: process.env.NODE_ENV ?? 'development', }, { // Optional: Dispatch tracking data when component mounts dispatchOnMount: true, // Optional: Custom merge options for tracking objects (since v9.3.0) mergeOptions: { isMergeableObject: obj => !(obj instanceof Date || obj instanceof RegExp), }, } ); useEffect(() => { // Example: Log current tracking data when component mounts console.log('Current tracking context:', getTrackingData()); }, []); const handleProductClick = (productId: string) => { // Imperatively dispatch an event trackEvent({ action: 'product_click', productId: productId, timestamp: new Date().toISOString(), }); }; return ( <Track> {/* Use <Track> to pass context to children */} <div> <h1>{pageName} for User: {userId}</h1> <p>This is a product page example.</p> <button onClick={() => handleProductClick('product-123')}> Click to Track Product 123 </button> <button onClick={() => trackEvent({ action: 'promo_view', promoId: 'summer_sale' })}> Track Promo View </button> </div> </Track> ); }; // Example of usage: // <ProductPage userId="user-abc" pageName="Electronics-Category" /> export default ProductPage;
Debug
Known issues
breakingVersion 9.0.0 removed `core-js` polyfills from the bundle to reduce build size. Applications must now provide their own polyfills if targeting older browser environments.
fix
Ensure your application's build process or entry points include necessary polyfills (e.g., via `core-js`, Babel, or polyfill.io) if your target browsers require them.
affects: >=9.0.0
gotchaWhen using the HoC/decorator pattern, accessing the underlying component's ref requires explicitly setting `forwardRef: true` in the options. Failing to do so will result in the ref pointing to the HoC wrapper instead of the intended component.
fix
For decorator usage, pass `{ forwardRef: true }` as the second argument: `@track({}, { forwardRef: true })`. This allows `ref` to correctly point to the decorated component instance.
affects: >=8.0.0
gotchaPrior to v7.3.0, decorating asynchronous methods (or methods returning Promises) could lead to incorrect return values or `TypeError` exceptions if `trackEvent` was called with `null`.
fix
Upgrade to `react-tracking@7.3.0` or newer. If stuck on older versions, ensure decorated async methods explicitly return their original promise or handle `trackEvent` calls carefully.
affects: <7.3.0
gotchaWhen `dispatchOnMount` is provided as a function, it is called in a `useEffect` on the component's initial render with all tracking context data. Be mindful of potential side effects or performance implications if the function performs heavy operations.
fix
Ensure the `dispatchOnMount` function is optimized for performance and idempotent, as it runs on every initial render. Avoid unnecessary complex logic within this function.
affects: *
gotchaVersion 9.3.0 of `react-tracking` temporarily dropped support for Node.js 16.9+ due to an oversight, only to re-enable it in 9.3.1. Ensure you are on 9.3.1 or later if using Node.js 16.9+.
fix
Upgrade to `react-tracking@9.3.1` or newer if your project relies on Node.js 16.9+ environments.
affects: 9.3.0
Errors
Common errors & fixes
TypeError: Cannot destructure property `trackEvent` of 'null' or 'undefined'
Decorating an async method in `react-tracking` versions prior to 7.3.0 could lead to `trackEvent` being called with `null` or an unexpected value when an error occurred.
fix
Upgrade `react-tracking` to version `7.3.0` or newer. If unable to upgrade, ensure your decorated async methods handle potential `null` or `undefined` values when calling `trackEvent`.
Error: Invalid hook call. Hooks can only be called inside of the body of a function component.
`useTracking` or other React Hooks are being called outside of a functional React component or a custom Hook.
fix
Ensure `useTracking` is only invoked directly within the body of a React functional component or another custom React Hook function. Do not call Hooks from regular JavaScript functions, class components, or event handlers directly.
Module not found: Error: Can't resolve 'react-tracking'
The `react-tracking` package is not installed, or there is a typo in the import path.
fix
Run `npm install --save react-tracking` or `yarn add react-tracking`. Double-check the import statement for any typos, ensuring it is `import { useTracking } from 'react-tracking';` or `import track from 'react-tracking';`.
Upgrade
Version history
9.3.2latest on npm
Audit
Dependencies
reactrequiredPeer dependency required for all React component usage (HoCs, Hooks).
prop-typesoptionalPeer dependency for type checking in React components, common for HoC/decorator usage.
Agent activity
14 hits · last 30 days
node
12
OpenAI (training)
2
Resources
react-tracking — npm install react-tracking · libregistry