React Marketing Tools

One track() call for Google Tag Manager, Google Analytics 4 and the Meta Pixel, with Consent Mode v2, UTM attribution and personal-data redaction built in.

Try it in the playground: see what each vendor receives for every event, without sending anything.

1.0 is in beta on the next tag. npm install react-marketing-tools still installs 0.4.x, whose API 1.0 replaces; see the migration guide and the changelog.

Install

npm install react-marketing-tools@next

Requires React 18 or 19. The package is ESM-only; server rendering needs Node.js 22.12 or later.

Usage

Create one instance:

// analytics.ts
import { createAnalytics } from 'react-marketing-tools'

export const analytics = createAnalytics({
  consent: 'denied', // until your consent banner records the visitor's choice
  gtm: { containerId: 'GTM-XXXXXXX' },
  ga4: { measurementId: 'G-XXXXXXX' },
  metaPixel: { pixelId: '1234567890123456' },
})

Provide it to your app:

// main.tsx
import { AnalyticsProvider } from 'react-marketing-tools'
import { analytics } from './analytics'

createRoot(document.getElementById('root')!).render(
  <AnalyticsProvider analytics={analytics}>
    <App />
  </AnalyticsProvider>,
)

Track from any component:

import { useAnalytics } from 'react-marketing-tools'

export const SignUpButton = () => {
  const { track } = useAnalytics()

  // Reaches GTM, GA4 and Meta (as CompleteRegistration) with one shared event_id
  return <button onClick={() => track('sign_up', { method: 'google' })}>Sign up</button>
}

Or without code, with autocapture: { clicks: true } in the config:

<button data-analytics-event="cta_click" data-analytics-param-location="hero">Start</button>

Follow a multi-step flow as a funnel:

const checkout = analytics.journey('checkout')
checkout.step('shipping') // journey_start, then journey_step
checkout.complete({ value: 42, currency: 'USD' }) // journey_complete

Report Core Web Vitals (LCP, INP, CLS) to GA4 and Tag Manager, after npm install web-vitals@^6:

import { trackWebVitals } from 'react-marketing-tools/web-vitals'

void trackWebVitals(analytics)

The same instance identifies users, records consent and gives a consenting visitor a stable ID:

analytics.identify('user-42', { email: 'ada@example.com' }) // user id for GTM and GA4, advanced matching for Meta
analytics.consent.update({ analytics: 'granted', ads: 'granted' }) // Google Consent Mode v2 and Meta consent
const visitorId = await analytics.getVisitorId() // random by default, or a fingerprint; never sent to GA4

Configure only the destinations you use. Without React, import createAnalytics from react-marketing-tools/core and call analytics.start() yourself.

Send events that happen on your server, such as a purchase confirmed by a payment webhook, from react-marketing-tools/server:

import { sendMeasurementProtocolEvent } from 'react-marketing-tools/server'

await sendMeasurementProtocolEvent({
  measurementId: 'G-XXXXXXX',
  apiSecret: process.env.GA4_API_SECRET!,
  clientId: order.ga4ClientId, // saved at checkout with readGa4Cookies()
  events: [{ name: 'purchase', params: { transaction_id: order.id, value: 42, currency: 'USD' } }],
})

sendConversionsApiEvent does the same for Meta, hashing customer information as Meta requires. To have Meta receive the events the browser Pixel misses, counted once, relay them through your server:

// analytics.ts
createAnalytics({ /* …as above */ server: { endpoint: '/api/track' } })

// app/api/track/route.ts (Next.js; any Request → Response server works)
import { createTrackHandler } from 'react-marketing-tools/server'

export const POST = createTrackHandler({
  allowedOrigins: ['https://shop.example.com'],
  meta: { pixelId: '1234567890123456', accessToken: process.env.META_CAPI_TOKEN! },
})

What each destination receives

	Google Tag Manager	Google Analytics 4	Meta Pixel	Conversions API relay
track()	dataLayer push with event_id	gtag.js event	standard or custom event with eventID	the same event from your server
identify()	user_id	user_id	advanced matching	user data, hashed on your server
consent.update()	Consent Mode v2	Consent Mode v2	grant / revoke	only with adUserData
Attribution	attribution (last touch)	read from the page URL	fbc	fbc, fbp

Documentation

• All docs
• Getting started
• React: provider, hook, Next.js App Router, single-page apps
• Tracking events: naming rules, page views, journeys, click autocapture, Web Vitals, users, personal data, errors
• Configuration
• Consent: Consent Mode v2 and Global Privacy Control
• Attribution: UTM params and ad click IDs
• Visitor ID: a stable ID for consenting visitors, random or fingerprint
• Google Tag Manager
• Google Analytics 4
• Meta Pixel
• Server-side tagging
• GA4 Measurement Protocol: GA4 events from your server
• Meta Conversions API: Meta events from your server
• Debugging: see what's sent, and fix common problems
• Migrating from 0.4
• Changelog

License

MIT