{"id":16884,"library":"react-server-side-gtm","title":"React Google Tag Manager with Server-Side Tagging","description":"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.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/pieperz/react-server-side-gtm","tags":["javascript","react","reactjs","react-component","google tag manager","tag manager","gtm"],"install":[{"cmd":"npm install react-server-side-gtm","lang":"bash","label":"npm"},{"cmd":"yarn add react-server-side-gtm","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-server-side-gtm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ES Module syntax. CommonJS `require` is not officially supported and may lead to issues, especially in modern React build environments.","wrong":"const TagManager = require('react-server-side-gtm');","symbol":"TagManager","correct":"import TagManager from 'react-server-side-gtm';"},{"note":"Ensure you call `initialize` only once, typically at your application's entry point. Subsequent data pushes should use `TagManager.dataLayer`.","wrong":"TagManager.init({ gtmId: 'GTM-XXXXXX' });","symbol":"TagManager.initialize","correct":"TagManager.initialize({ gtmId: 'GTM-XXXXXX' });"},{"note":"After initial setup, use `dataLayer` to push new events or data to the GTM dataLayer. Do not call `initialize` again for subsequent pushes.","wrong":"TagManager.initialize({ dataLayer: { event: 'my_event' } });","symbol":"TagManager.dataLayer","correct":"TagManager.dataLayer({ dataLayer: { event: 'my_event' } });"}],"quickstart":{"code":"import React, { useEffect } from 'react';\nimport TagManager from 'react-server-side-gtm';\n\nconst GtmInitializer = () => {\n useEffect(() => {\n const gtmId = process.env.NEXT_PUBLIC_GTM_ID ?? 'GTM-XXXXXX'; // Use env var or default\n\n if (gtmId === 'GTM-XXXXXX') {\n console.warn('GTM ID is not configured. Using placeholder GTM-XXXXXX. Please set NEXT_PUBLIC_GTM_ID.');\n }\n\n // Initialize GTM when the component mounts\n TagManager.initialize({\n gtmId: gtmId,\n dataLayer: {\n event: 'page_view',\n pagePath: window.location.pathname,\n pageTitle: document.title,\n userId: 'USER_12345', // Example custom user ID\n userProject: 'web_application',\n },\n // Optional: Specify a custom dataLayer name if needed\n // dataLayerName: 'myCustomDataLayer',\n // Optional: Configure custom GTM server-side container endpoint\n // src: 'https://your-custom-gtm-server.com',\n });\n\n // Simulate a user action after some time\n const timer = setTimeout(() => {\n TagManager.dataLayer({\n dataLayer: {\n event: 'promo_view',\n promotionId: 'SUMMER_SALE',\n position: 'top_banner'\n },\n });\n console.log('Pushed a simulated promo_view event to dataLayer.');\n }, 3000);\n\n return () => clearTimeout(timer);\n }, []);\n\n const handleProductClick = (productId) => {\n TagManager.dataLayer({\n dataLayer: {\n event: 'product_click',\n productId: productId,\n category: 'Electronics',\n list: 'Search Results'\n },\n });\n alert(`Product ${productId} clicked! Event sent to GTM.`);\n };\n\n return (\n
\n

Welcome to your Application!

\n

This page integrates Google Tag Manager for analytics and server-side tagging.

\n \n

Open your browser's developer tools and check the Network tab or GTM Debugger for dataLayer events.

\n
\n );\n};\n\nexport default GtmInitializer;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"This 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"Calling `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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `TagManager` object was not correctly imported or the library was not installed.","error":"ReferenceError: TagManager is not defined"},{"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.","cause":"Incorrect `gtmId`, missing `src` for server-side tagging, or events are not correctly pushed to the dataLayer.","error":"GTM events are not appearing in Google Analytics, Tag Manager Debugger, or your GTM server container."},{"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.","cause":"The initial `TagManager.initialize` call didn't include the custom dataLayer, or a subsequent `TagManager.initialize` call overwrote it instead of pushing new data.","error":"Custom dataLayer values (e.g., `userId`, `userProject`) are not present or are overwritten in GTM."}],"ecosystem":"npm","meta_description":null}