Google Tag Manager on Hygraph (GraphCMS) | OpsBlu Docs

Google Tag Manager on Hygraph (GraphCMS)

How to install and configure Google Tag Manager on Hygraph (GraphCMS). Covers installation method, container setup, verification, and Hygraph...

For general GTM concepts, see Google Tag Manager Overview

Overview

Hygraph (formerly GraphCMS) is a headless GraphQL CMS with no frontend rendering. GTM goes in the frontend that consumes Hygraph's GraphQL API.

Prerequisites

Installation

Headless CMS — Frontend Framework Installation

Since Hygraph (GraphCMS) is a headless CMS, it delivers content via API — it does not render HTML pages. GTM must be installed in whatever frontend framework consumes the Hygraph (GraphCMS) API.

Where to add GTM: In your frontend app's HTML entry point or document component

Next.js

// pages/_document.tsx (Pages Router) or app/layout.tsx (App Router)
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script id="gtm" strategy="afterInteractive">
          {`(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
          new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
          j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
          'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
          })(window,document,'script','dataLayer','GTM-XXXXXXX');`}
        </Script>
      </head>
      <body>
        <noscript>
          <iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
            height="0" width="0" style={{display:'none',visibility:'hidden'}} />
        </noscript>
        {children}
      </body>
    </html>
  );
}

Gatsby

Install the official plugin:

npm install gatsby-plugin-google-tagmanager

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-google-tagmanager',
      options: {
        id: 'GTM-XXXXXXX',
        includeInDevelopment: false,
      },
    },
  ],
};

Nuxt 3

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          innerHTML: `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
          new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
          j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
          'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
          })(window,document,'script','dataLayer','GTM-XXXXXXX');`,
        },
      ],
    },
  },
});

Static HTML / Vanilla SPA

Add the standard GTM snippets to your index.html:

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXXX');</script>
<!-- End Google Tag Manager -->

<!-- Google Tag Manager (noscript) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<!-- End Google Tag Manager (noscript) -->

Replace GTM-XXXXXXX with your actual Container ID in both snippets.

Hygraph (GraphCMS)-Specific Considerations

Hygraph serves content via GraphQL API only. Your frontend framework handles all HTML rendering. If using Next.js, Gatsby, or Nuxt, add GTM via their document/head APIs.

Verification

After installation, verify GTM is working:

  1. GTM Preview Mode — In GTM, click Preview, enter your site URL, and verify the container loads.
  2. Browser Console — Open DevTools (F12) and run console.log(window.google_tag_manager). You should see an object (not undefined).
  3. Network Tab — Filter for googletagmanager.com and verify gtm.js loads with a 200 response.
  4. Data Layer Check — Run console.log(window.dataLayer) to verify the data layer array exists.

SPA Route Changes

Since Hygraph (GraphCMS)-powered sites typically use client-side routing, standard GTM page view tracking won't capture navigation after the initial load. In GTM, create a History Change trigger and use it alongside (or instead of) the All Pages trigger for your GA4 page view tag.

Next Steps

Back to top