Google Tag Manager Loader

A lightweight, promise-based Google Tag Manager (GTM) script loader for modern web applications. Built with TypeScript and powered by @zoltanradics/async-script-loader.

Features

• Promise-based API - Know exactly when GTM is loaded and ready
• TypeScript Support - Full type definitions included
• Lightweight - Only 0.57 kB (gzipped: 0.38 kB)
• Modern ESM - ES Module format for optimal tree-shaking
• Zero Dependencies - Only one peer dependency for script injection
• Customizable DataLayer - Support for custom dataLayer names
• Browser Environment Detection - Automatic checks for safe loading

Installation

npm install @zoltanradics/gtm-loader

Or with yarn:

yarn add @zoltanradics/gtm-loader

Or with pnpm:

pnpm add @zoltanradics/gtm-loader

Usage

Basic Usage

import googleTagManagerLoader from '@zoltanradics/gtm-loader';

// Load GTM with your container ID
googleTagManagerLoader('GTM-XXXXXX')
  .then(() => {
    console.log('GTM loaded successfully!');
    // GTM is now ready, tags will start firing
  })
  .catch((error) => {
    console.error('Failed to load GTM:', error);
  });

With Async/Await

import googleTagManagerLoader from '@zoltanradics/gtm-loader';

async function initializeAnalytics() {
  try {
    await googleTagManagerLoader('GTM-XXXXXX');
    console.log('GTM loaded successfully!');
  } catch (error) {
    console.error('Failed to load GTM:', error);
  }
}

initializeAnalytics();

Custom DataLayer Name

import googleTagManagerLoader from '@zoltanradics/gtm-loader';

// Use a custom dataLayer name
googleTagManagerLoader('GTM-XXXXXX', 'myCustomDataLayer')
  .then(() => {
    console.log('GTM loaded with custom dataLayer!');
  });

React Example

import { useEffect } from 'react';
import googleTagManagerLoader from '@zoltanradics/gtm-loader';

function App() {
  useEffect(() => {
    googleTagManagerLoader('GTM-XXXXXX')
      .then(() => console.log('GTM loaded'))
      .catch((error) => console.error('GTM error:', error));
  }, []);

  return <div>Your App</div>;
}

Vue Example

<script setup>
import { onMounted } from 'vue';
import googleTagManagerLoader from '@zoltanradics/gtm-loader';

onMounted(async () => {
  try {
    await googleTagManagerLoader('GTM-XXXXXX');
    console.log('GTM loaded');
  } catch (error) {
    console.error('GTM error:', error);
  }
});
</script>

API

googleTagManagerLoader(containerId, dataLayerKey?)

Loads the Google Tag Manager script asynchronously.

Parameters

• containerId (string, required) - Your GTM container ID (e.g., 'GTM-XXXXXX')
• dataLayerKey (string, optional) - Custom dataLayer name (defaults to 'dataLayer')

Returns

• Promise<void> - Resolves when GTM script is successfully loaded, rejects on error

Throws

• Error - If called in a non-browser environment (no window object)
• Error - If containerId is undefined or invalid

How It Works

1. Environment Check - Verifies execution in a browser environment
2. DataLayer Initialization - Creates or uses existing window.dataLayer with GTM start event
3. Script Injection - Uses @zoltanradics/async-script-loader to load gtm.js
4. Promise Resolution - Returns promise that resolves when script loads successfully

Browser Support

Works in all modern browsers that support:

• ES2020
• ES Modules
• Promises
• Native async/await

Demo

Check out the live demo to see the loader in action with real-time logging and dataLayer monitoring.

Development

Setup

# Install dependencies
npm install

# Start development server
npm run dev

# Build the library
npm run build

# Run demo in development
npm run demo:dev

# Build demo for deployment
npm run demo:build

Project Structure

├── src/
│   └── google-tag-manager-loader.ts  # Main source file
├── demo/
│   ├── index.html                    # Demo page
│   ├── demo.js                       # Demo logic
│   └── style.css                     # Demo styles
├── dist/                             # Built library (generated)
├── dist-demo/                        # Built demo (generated)
└── package.json

Why Use This Loader?

Instead of Direct Script Tag

<!-- Traditional approach -->
<script>(function(w,d,s,l,i){...})(window,document,'script','dataLayer','GTM-XXXXXX');</script>

Benefits of using this loader:

• ✅ Promise-based - Know when GTM is ready
• ✅ Error handling - Catch loading failures
• ✅ TypeScript types - Full IDE support
• ✅ Tree-shakeable - Optimal bundle size
• ✅ Testable - Easy to mock in tests
• ✅ Modern - Follows JavaScript best practices

Related Packages

• @zoltanradics/async-script-loader - The underlying script injection library

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Issues: GitHub Issues
• NPM: @zoltanradics/gtm-loader

License

MIT © Zoltan Radics

Made with ❤️ by Zoltan Radics