Registry / observability / react-gtm-module

react-gtm-module

library2.0.11jsnpmunverified

react-gtm-module is a JavaScript library designed for React applications to streamline the integration of Google Tag Manager (GTM). It provides a programmatic API for managing the GTM snippet, initializing GTM with a specific container ID, and interacting with the `dataLayer` object. The current stable version is 2.0.11, last updated in November 2022. While the package remains functional, the original repository (alinemorelli/react-gtm) has seen limited activity since late 2020, with many pull requests and issues unaddressed. A community-maintained fork, `@sooro-io/react-gtm-module`, has emerged to provide continued development, TypeScript support, and additional features like CSP nonce and custom GTM script URLs. This original package (`react-gtm-module`) offers a straightforward abstraction for common GTM operations, simplifying custom `dataLayer` pushes, multiple `dataLayer` instances, and environment-specific GTM configurations without direct `window.dataLayer` manipulation.

observability web-framework

npm install react-gtm-module

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-GTM-MODULE

react-gtm-module

observabilityjavascriptv2.0.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

TagManager

✓ import TagManager from 'react-gtm-module'

✗ import { TagManager } from 'react-gtm-module'

The library exports `TagManager` as a default export, not a named export. Ensure curly braces are not used.

TagManager.initialize

✓ TagManager.initialize({ gtmId: 'GTM-XXXXXX' })

This function is used to inject the GTM script and optionally push initial `dataLayer` variables. It should typically be called once early in your application's lifecycle.

TagManager.dataLayer

✓ TagManager.dataLayer({ dataLayer: { event: 'productClick', productId: '123' } })

✗ window.dataLayer.push({ event: 'productClick', productId: '123' })

Use `TagManager.dataLayer` for pushing events or data to the GTM `dataLayer` to maintain consistency and leverage the library's abstraction, especially when using a custom `dataLayerName`.

Initializes Google Tag Manager with a specified ID and initial `dataLayer` values. It also demonstrates how to push a custom event to the `dataLayer` after initialization using a button click, simulating common tracking scenarios.

import React from 'react'; import ReactDOM from 'react-dom/client'; import TagManager from 'react-gtm-module'; // Replace 'GTM-XXXXXX' with your actual Google Tag Manager ID const GTM_ID = process.env.GTM_ID ?? 'GTM-DEFAULT'; const tagManagerArgs = { gtmId: GTM_ID, dataLayer: { userId: '12345', page: 'AppInitialization', status: 'logged_in', }, events: { initEvent: 'gtm.js' } }; TagManager.initialize(tagManagerArgs); const App = () => { // Example of pushing an event after initialization const trackButtonClick = () => { TagManager.dataLayer({ dataLayer: { event: 'buttonClick', category: 'Interaction', action: 'Click Me', label: 'Homepage Button' } }); console.log('Button click event pushed to DataLayer'); }; return ( <div> <h1>Welcome to the React GTM App</h1> <button onClick={trackButtonClick}>Track This Button</button> <p>GTM is initialized with ID: {GTM_ID}</p> <p>Check your GTM debug view or browser console for dataLayer pushes.</p> </div> ); }; const root = ReactDOM.createRoot(document.getElementById('root')); root.render( <React.StrictMode> <App /> </React.StrictMode> );

Debug

Known issues

gotchaEnsure your `gtmId` is correct (e.g., `GTM-XXXXXX`). An incorrect ID can lead to a 404 error for the GTM script and no data being collected.

fix

Verify the GTM ID in your Google Tag Manager account settings and ensure it matches the ID passed to `TagManager.initialize`.

affects: >=1.0.0

breakingThe `events` argument behavior in `TagManager.initialize` had a bug fix in the `@sooro-io/react-gtm-module` fork, which constituted a breaking change from the original `react-gtm-module`. If relying on initial events pushed via `initialize`, test thoroughly or consider migrating to the fork.

fix

For the original `react-gtm-module`, carefully review the `events` functionality. For consistent and updated behavior, consider migrating to `@sooro-io/react-gtm-module` and consult its migration guide.

affects: <2.0.11

gotchaAvoid manually adding the GTM snippet to your `index.html` if using `react-gtm-module`. Doing so will result in double-tagging and potentially inaccurate data collection.

fix

Remove any manually placed GTM `<script>` tags from your `public/index.html` or equivalent file once `TagManager.initialize` is used.

affects: >=1.0.0

gotchaIf using a custom `dataLayerName`, ensure consistency. If `TagManager.initialize` is called with `dataLayerName: 'MyDataLayer'`, subsequent `TagManager.dataLayer` calls must also specify `dataLayerName: 'MyDataLayer'` to push to the correct `dataLayer` instance.

fix

Always pass the `dataLayerName` option to both `TagManager.initialize` and `TagManager.dataLayer` if you are using a custom `dataLayer` name.

affects: >=1.0.0

deprecatedThe original `react-gtm-module` package has not been actively developed since late 2020. Consider using the community-maintained fork `@sooro-io/react-gtm-module` for ongoing support, new features (like CSP nonce and custom GTM script URLs), and TypeScript definitions.

fix

Migrate your project to use `@sooro-io/react-gtm-module` by uninstalling `react-gtm-module` and installing `@sooro-io/react-gtm-module`, then updating import paths.

affects: >=2.0.0

Errors

Common errors & fixes

Uncaught ReferenceError: TagManager is not defined

The `TagManager` object was not imported or the import path is incorrect.

fix

Ensure `import TagManager from 'react-gtm-module'` is present at the top of your file before `TagManager` is used.

Error: GTM ID is required

The `gtmId` property was not provided or was empty in the `tagManagerArgs` object during `TagManager.initialize`.

fix

Pass a valid GTM container ID (e.g., `GTM-XXXXXX`) as the `gtmId` property to the `TagManager.initialize` function.

GTM script returns 404 error in network requests

The provided GTM ID is incorrect, or the GTM container associated with the ID has not been published in Google Tag Manager.

fix

Double-check your `gtmId` for typos. Ensure you have published at least one version of your GTM container in the Google Tag Manager interface.

Upgrade

Version history

2.0.11latest on npm

Audit

Dependencies

reactrequiredPeer dependency, as this is a React component module.

react-domrequiredPeer dependency, for rendering React components.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/alinemorelli/react-gtm ↗

packagehttps://www.npmjs.com/package/react-gtm-module ↗