Declarative Tracking for React Apps

Common errors

• TypeError: Cannot destructure property `trackEvent` of 'null' or 'undefined'

  cause 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.

  cause `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'

  cause 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';`.

Warnings

• breaking Version 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.
• gotcha When 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.
• gotcha Prior 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.
• gotcha When `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.
• gotcha Version 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.

Install

• npm install react-tracking npm
• yarn add react-tracking yarn
• pnpm add react-tracking pnpm

Imports

• track
  wrong:

  import { track } from 'react-tracking';

  correct:

  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
  wrong:

  const { useTracking } = require('react-tracking');

  correct:

  import { useTracking } from '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
  wrong:

  import { track } from 'react-tracking';

  correct:

  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
  wrong:

  import deepmerge from 'deepmerge';

  correct:

  import { deepmerge } from 'react-tracking';

  Re-exported for convenience since v9.2.0, useful when providing custom `mergeOptions` or needing deep merging capabilities with tracking data.

Quickstart

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;