React Facebook Pixel

Common errors

• ReferenceError: window is not defined

  cause The library directly references the global `window` object, which is not available in Node.js environments (e.g., server-side rendering in Next.js, Gatsby, or during build processes in CI).
  fix Wrap `ReactPixel` calls in `if (typeof window !== 'undefined') { ... }` blocks. For Next.js, dynamic imports with `ssr: false` are often the most robust solution. When using CommonJS `require()`, use `require('react-facebook-pixel').default`.

• TypeError: src_default(...).track is not a function

  cause This error typically occurs when using CommonJS `require('react-facebook-pixel')` without explicitly accessing the `.default` export, especially in bundled environments or when the module's export structure is misunderstood.
  fix Ensure you are using `const ReactPixel = require('react-facebook-pixel').default;` when importing via CommonJS. If using ES Modules, `import ReactPixel from 'react-facebook-pixel';` is correct.

• Property 'fbq' does not exist on type 'Window'

  cause When directly interacting with `window.fbq` in TypeScript without proper global type declarations, the TypeScript compiler will report this error.
  fix Add a global type declaration for `window.fbq` in your project (e.g., in a `global.d.ts` file) or use the `react-facebook-pixel` library's provided API which should have types. Example: `declare global { interface Window { fbq?: FacebookPixelFunction; } }`.

Warnings

• gotcha The library directly accesses the `window` object, which causes `ReferenceError: window is not defined` errors during server-side rendering (SSR) or in Node.js environments like Next.js or during CI builds.
  Fix: Conditionally import the library or wrap its initialization and usage in `typeof window !== 'undefined'` checks. For CommonJS `require()`, specifically use `require('react-facebook-pixel').default` in non-browser environments. For Next.js, consider dynamic imports with `ssr: false`.
• gotcha To ensure GDPR compliance, explicit consent management is required. The library provides `revokeConsent()` and `grantConsent()` methods, which developers must integrate into their UI/UX flow.
  Fix: Call `ReactPixel.revokeConsent()` after initialization and then `ReactPixel.grantConsent()` only after the user explicitly accepts tracking cookies. This ensures no data is sent before consent is given.
• deprecated The `react-facebook-pixel` package has been effectively abandoned, with its last npm publication over five years ago (December 2020). This means it is unlikely to receive updates for new Facebook Pixel API changes, security vulnerabilities, or compatibility fixes for newer React versions.
  Fix: Consider migrating to actively maintained alternatives like `react-facebook` (which includes pixel tracking) or `react-use-facebook-pixel` for ongoing support and features. These alternatives offer better SSR support, modern React patterns (hooks), and updated type definitions.

Install

• npm install react-facebook-pixel npm
• yarn add react-facebook-pixel yarn
• pnpm add react-facebook-pixel pnpm

Imports

• ReactPixel

  import ReactPixel from 'react-facebook-pixel';

  This is the primary way to import the library using ES Modules for browser-side React applications.
• ReactPixel
  wrong:

  const ReactPixel = require('react-facebook-pixel');

  correct:

  const ReactPixel = require('react-facebook-pixel').default;

  When using CommonJS `require()` in environments like Node.js or during server-side rendering (SSR), accessing the `.default` property is necessary to retrieve the module's main export. Omitting `.default` is a common mistake that leads to errors, especially in CI/bundling environments.
• typeof ReactPixel

  import type ReactPixelType from 'react-facebook-pixel';

  While the library ships with TypeScript types, direct type imports are typically used for the default export. However, due to its abandonment, type definitions might not be up-to-date with current TypeScript standards or Meta Pixel API changes.

Quickstart

This quickstart demonstrates how to initialize the Facebook Pixel, track a page view on component mount, and trigger a custom 'Purchase' event. It also includes the crucial `typeof window !== 'undefined'` check for SSR compatibility and shows how to use the GDPR consent features.

import ReactPixel from 'react-facebook-pixel';
import { useEffect } from 'react';

const advancedMatching = { em: 'some@email.com' }; // Optional for advanced matching
const options = {
  autoConfig: true, // Enables pixel's autoConfig
  debug: false, // Disables logs
};

function App() {
  useEffect(() => {
    // Ensure window is defined before initializing (for SSR compatibility)
    if (typeof window !== 'undefined') {
      ReactPixel.init('yourPixelIdGoesHere', advancedMatching, options);
      ReactPixel.pageView(); // Track initial page view
    }
  }, []);

  const handleProductPurchase = (productId, price) => {
    if (typeof window !== 'undefined') {
      ReactPixel.track('Purchase', { value: price, currency: 'USD', content_ids: [productId], content_type: 'product' });
    }
  };

  return (
    <div>
      <h1>My React App</h1>
      <p>Welcome to the homepage. We track page views.</p>
      <button onClick={() => handleProductPurchase('product123', 99.99)}>
        Buy Product 123
      </button>
      <p>Please remember to handle GDPR consent explicitly.</p>
      <button onClick={ReactPixel.grantConsent}>Accept Cookies</button>
    </div>
  );
}

export default App;