Skip to content

astro-gtm

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

astro-gtm

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
AGENTS.md
AGENTS.md
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 
tsup.config.ts
tsup.config.ts
 
 

README.md

🚀 Astro Google Tag Manager

version downloads github actions typescript makepr Built with Astro

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

Type Description
ad_storage Enables storage for advertising purposes
analytics_storage Enables storage for analytics purposes
ad_user_data Consent for sending user data to Google
ad_personalization Consent for personalized advertising
functionality_storage Enables storage for website functionality
personalization_storage Enables storage for personalization
security_storage Enables storage for security purposes

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:

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

📝 Changelog

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