Registry / http-networking / react-server-side-gtm

react-server-side-gtm

JSON →
library3.0.1jsnpmunverified

react-server-side-gtm is a React component library designed for integrating Google Tag Manager (GTM) into React applications, with a particular focus on robust server-side tagging capabilities. As an actively maintained fork of the `react-gtm-module` library, it addresses the original project's stagnation by providing more active development and support for newer GTM features. The current stable version is `3.0.1`, with recent `v3.0.0` releases indicating an active development cycle and a steady release cadence. Key differentiators include enhanced support for server-side tagging, offering greater control over data and improved privacy compliance. It also provides flexible options for custom and multiple `dataLayer` configurations, facilitates the integration of additional events, and allows for specific configurations for custom GTM server-side containers and different deployment environments. This library is well-suited for React projects requiring advanced GTM implementations beyond basic client-side tracking, especially those leveraging the performance, security, and data accuracy benefits of server-side Google Tag Manager.

npm install react-server-side-gtm
INSTALL
IMPORT
SIG · REACT-SERVER-SIDE-
R
react-server-side-gtm
http-networkingjavascriptv3.0.1
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.

TagManager
import TagManager from 'react-server-side-gtm';
const TagManager = require('react-server-side-gtm');
The library primarily uses ES Module syntax. CommonJS `require` is not officially supported and may lead to issues, especially in modern React build environments.
TagManager.initialize
TagManager.initialize({ gtmId: 'GTM-XXXXXX' });
TagManager.init({ gtmId: 'GTM-XXXXXX' });
Ensure you call `initialize` only once, typically at your application's entry point. Subsequent data pushes should use `TagManager.dataLayer`.
TagManager.dataLayer
TagManager.dataLayer({ dataLayer: { event: 'my_event' } });
TagManager.initialize({ dataLayer: { event: 'my_event' } });
After initial setup, use `dataLayer` to push new events or data to the GTM dataLayer. Do not call `initialize` again for subsequent pushes.

This quickstart initializes Google Tag Manager upon component mount, pushes initial page view data to the dataLayer, and demonstrates how to push custom events triggered by user actions or asynchronous operations, incorporating environment variables for GTM ID.

import React, { useEffect } from 'react'; import TagManager from 'react-server-side-gtm'; const GtmInitializer = () => { useEffect(() => { const gtmId = process.env.NEXT_PUBLIC_GTM_ID ?? 'GTM-XXXXXX'; // Use env var or default if (gtmId === 'GTM-XXXXXX') { console.warn('GTM ID is not configured. Using placeholder GTM-XXXXXX. Please set NEXT_PUBLIC_GTM_ID.'); } // Initialize GTM when the component mounts TagManager.initialize({ gtmId: gtmId, dataLayer: { event: 'page_view', pagePath: window.location.pathname, pageTitle: document.title, userId: 'USER_12345', // Example custom user ID userProject: 'web_application', }, // Optional: Specify a custom dataLayer name if needed // dataLayerName: 'myCustomDataLayer', // Optional: Configure custom GTM server-side container endpoint // src: 'https://your-custom-gtm-server.com', }); // Simulate a user action after some time const timer = setTimeout(() => { TagManager.dataLayer({ dataLayer: { event: 'promo_view', promotionId: 'SUMMER_SALE', position: 'top_banner' }, }); console.log('Pushed a simulated promo_view event to dataLayer.'); }, 3000); return () => clearTimeout(timer); }, []); const handleProductClick = (productId) => { TagManager.dataLayer({ dataLayer: { event: 'product_click', productId: productId, category: 'Electronics', list: 'Search Results' }, }); alert(`Product ${productId} clicked! Event sent to GTM.`); }; return ( <div> <h1>Welcome to your Application!</h1> <p>This page integrates Google Tag Manager for analytics and server-side tagging.</p> <button onClick={() => handleProductClick('P1001')}>View Product P1001</button> <p>Open your browser's developer tools and check the Network tab or GTM Debugger for dataLayer events.</p> </div> ); }; export default GtmInitializer;
Debug
Known issues
breakingThis library is a fork of `react-gtm-module`. While the API is largely compatible, users migrating from the original package should review documentation for potential behavioral changes, new features, or slight API discrepancies introduced in `v3.0.0` and later.
fix
Thoroughly review the `react-server-side-gtm` README and API documentation for specific differences when migrating from `react-gtm-module`. Test your GTM integrations comprehensively after upgrading.
affects: >=3.0.0
gotchaFor server-side tagging to function correctly, your Google Tag Manager container and Google Cloud Platform setup must be configured specifically for server-side GTM. Simply installing this library is not sufficient.
fix
Ensure your Google Tag Manager container has a server-side client, and that your GTM server-side endpoint (e.g., `src` parameter in `TagManager.initialize`) points to your deployed GTM server container URL (e.g., `https://your-custom-gtm-server.com`). Refer to Google's official server-side tagging documentation.
affects: *
gotchaCalling `TagManager.initialize` multiple times with different dataLayer configurations can lead to unexpected behavior or data loss, as it re-initializes the GTM script and dataLayer.
fix
Call `TagManager.initialize` only once, typically at your application's root component or entry point. For subsequent data pushes or event triggers, use `TagManager.dataLayer` method to update the dataLayer safely.
affects: *
Errors
Common errors & fixes
ReferenceError: TagManager is not defined
The `TagManager` object was not correctly imported or the library was not installed.
fix
Ensure you have `npm install react-server-side-gtm` and use `import TagManager from 'react-server-side-gtm';` at the top of your file.
GTM events are not appearing in Google Analytics, Tag Manager Debugger, or your GTM server container.
Incorrect `gtmId`, missing `src` for server-side tagging, or events are not correctly pushed to the dataLayer.
fix
Double-check your `gtmId` for typos. If using server-side tagging, ensure the `src` parameter in `TagManager.initialize` points to your active GTM server container URL. Verify that `TagManager.dataLayer` calls include an `event` key and necessary parameters.
Custom dataLayer values (e.g., `userId`, `userProject`) are not present or are overwritten in GTM.
The initial `TagManager.initialize` call didn't include the custom dataLayer, or a subsequent `TagManager.initialize` call overwrote it instead of pushing new data.
fix
Ensure all initial `dataLayer` variables are passed in the `dataLayer` object during the initial `TagManager.initialize` call. For subsequent updates, use `TagManager.dataLayer({ dataLayer: { /* new data */ } })` to merge new data without overwriting.
Upgrade
Version history
3.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
19 hits · last 30 days
node
16
OpenAI (training)
2
Resources
react-server-side-gtm — npm install react-server-side-gtm · libregistry