astro-gtm

v1.1.0

Published

7 days ago

Astro plugin to easily integrate Google Tag Manager (GTM) into your astro site

0High
0Medium
0Low

mhdcodes

astro astro-gtm astro-integration astro-plugin analytics google-tag-manager gtm tag-manager

🚀 Astro Google Tag Manager

This Astro plugin makes it easy to integrate Google Tag Manager into your project, letting you manage marketing and analytics tags directly from your Astro website.

📋 Requirements

Astro 5.0 or higher
A Google Tag Manager account and container ID

📦 Installation

Install using pnpm:

pnpm add astro-gtm

Or using npm:

npm install astro-gtm

Or using yarn:

yarn add astro-gtm

🥑 Usage

Add the GoogleTagManager component to your layout or page:

---
import { GoogleTagManager } from 'astro-gtm';
---

<html lang="en">
  <head>
    <!-- Your head content -->
  </head>

  <body>
    <GoogleTagManager gtmId="GTM-XXXXXXX" />
    <slot />
  </body>
</html>

🔐 Using Environment Variables

It's recommended to store your GTM ID in environment variables rather than hardcoding it:

Step 1: Create `.env` file

# .env file in your project root
PUBLIC_GTM_ID=GTM-XXXXXXX

Important: Use the PUBLIC_ prefix for environment variables that need to be available in client-side code.

Step 2: Use in your component

---
import { GoogleTagManager } from 'astro-gtm';
---

<html lang="en">
  <head>
    <!-- Your head content -->
  </head>

  <body>
    <GoogleTagManager gtmId={import.meta.env.PUBLIC_GTM_ID} />
    <slot />
  </body>
</html>

Step 3: Add TypeScript types (optional)

Create or update src/env.d.ts:

/// <reference types="astro/client" />

interface ImportMetaEnv {
  readonly PUBLIC_GTM_ID: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

This provides autocompletion and type safety for your environment variables.

📖 API Reference

`<GoogleTagManager>`

| Name | Required | Default | Example | Description | | :---------------- | :------: | :-----------: | :----------------------------- | :--------------------------------------------------------------------------------------- | | gtmId | Yes | - | 'GTM-XXXXXXX' | Google Tag Manager container ID. | | dataLayer | No | - | { userId: '123', page: '/' } | Object that contains all of the information that you want to pass to Google Tag Manager. | | dataLayerName | No | 'dataLayer' | 'customDataLayer' | Custom name for dataLayer object. | | includeNoScript | No | true | false | Whether to include the noscript iframe. | | enableInDevMode | No | false | true | Whether to enable Google Tag Manager in development mode. | | auth | No | undefined | 'WFcfQBD6HDw' | Set preview auth for GTM workspace previews. | | preview | No | undefined | 'env-XXX' | Set preview environment ID for GTM workspace previews. | | defaultConsent | No | undefined | { ad_storage: 'denied' } | Default consent state for Google Consent Mode v2. Required for GDPR compliance. |

All props except gtmId are optional. The component will not render in development mode unless enableInDevMode is set to true.

🛡️ GDPR Compliance with Consent Mode

Google Tag Manager supports Consent Mode v2, which is required for GDPR compliance in Europe. This package makes it easy to set default consent states before GTM initializes.

Setting Default Consent

---
import { GoogleTagManager } from 'astro-gtm';
---

<GoogleTagManager
  gtmId="GTM-XXXXXXX"
  defaultConsent={{
    // Set default consent to 'denied' as a placeholder
    // Determine actual values based on your own requirements
    ad_storage: 'denied',
    ad_user_data: 'denied',
    ad_personalization: 'denied',
    analytics_storage: 'denied'
  }}
/>

Updating Consent After User Accepts

After the user accepts cookies through your consent banner, update the consent state:

<script>
  // In your consent banner component or script
  function allConsentGranted() {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push([
      'consent',
      'update',
      {
        ad_storage: 'granted',
        ad_user_data: 'granted',
        ad_personalization: 'granted',
        analytics_storage: 'granted'
      }
    ]);
  }
</script>
<!-- Invoke your consent functions when a user interacts with your banner -->
<button onclick="allConsentGranted()">Yes</button>

Available Consent Types

Note: When defaultConsent is omitted, no consent mode is configured and GTM behaves according to your tag configuration.

Learn more: Google Consent Mode Documentation

🔍 How It Works

This package adds the necessary Google Tag Manager scripts to your page's <body> tag. It:

Creates a data layer with your custom data
Injects the GTM script in the head of your document
Adds a noscript fallback (optional)
Automatically disables itself in development mode (unless explicitly enabled)

📝 Changelog

Please see the changelog for more information on what has changed recently.