Google Tag Manager DataLayer Type Generator (gtm-type-generator)

A CLI tool that automatically generates strict TypeScript definitions for your window.dataLayer.push method by directly fetching your configuration from the Google Tag Manager (GTM) API.

Why?

Without strict types, dataLayer.push is a black box. A typo in an event name or a missing variable can silently break your tracking. This tool solves that by looking at your actual GTM workspace and creating types that enforce correctness at compile time.

// With gtm-type-generator, this gives a TS error because 'method' is required for the 'login' event!
window.dataLayer.push({ event: 'login' }); 

// ✅ Correct
window.dataLayer.push({ event: 'login', method: 'Google' });

Features

• Type Safety: Enforces correct event names and their associated variables based on your actual GTM Triggers and Tags.
• Auto-Sync: Connects directly to the Tag Manager API v2 to fetch your latest container configuration.
• Seamless Integration: Designed to be run as an npm script to keep your codebase in sync with your GTM workspace.

Installation

npm install -D gtm-type-generator

Authentication Setup

To access the GTM API, you need a Google Service Account:

1. Go to the Google Cloud Console and enable the Tag Manager API.
2. Create a Service Account and download its JSON key file.
3. CRITICAL: Go to your Google Tag Manager Admin Panel, select "User Management", and invite the Service Account's email address with at least Read permissions for the target container.

Usage

1. Add an npm script

Add a script to your package.json to easily update your types:

{
  "scripts": {
    "update:gtm-type": "gtm-type-generator generate --account-id 123456 --container-id 987654 --workspace-id 2 --key-file ./gtm-service-account.json --output src/types/gtm.d.ts"
  }
}

Tip: You can also use environment variables (GTM_ACCOUNT_ID, GTM_CONTAINER_ID, GTM_WORKSPACE_ID, GOOGLE_APPLICATION_CREDENTIALS) instead of passing them as CLI flags.

Run the script:

npm run update:gtm-type

2. Configure TypeScript (tsconfig.json)

Ensure your TypeScript compiler includes the generated .d.ts file so it automatically extends the global Window interface across your project.

{
  "compilerOptions": {
    // ... other options
  },
  "include": [
    "src/**/*",
    "src/types/gtm.d.ts" // Ensure the output path is included here
  ]
}

Development

Prerequisites

• Node.js 20+
• npm

Setup

npm install

Scripts

• npm run build: Build the project using esbuild.
• npm test: Run unit tests using Vitest.
• npm run lint: Run ESLint to check for code style and potential errors.
• npm run lint -- --fix: Automatically fix linting issues.

CI/CD

This project uses GitHub Actions for continuous integration and delivery:

• CI: Runs on every push to main and all Pull Requests. It executes linting, tests, and a build to ensure code quality.
• Release: Automatically publishes to npm when a new tag starting with v (e.g., v1.0.0) is pushed to the repository. Note: Requires NPM_TOKEN to be set in GitHub Secrets.

Architecture & Extraction Process

This tool generates types by analyzing the relationships between Triggers, Tags, and Variables in your GTM workspace.

1. API Client: Authenticates and fetches Triggers, Tags, and Variables from the specified GTM workspace.
2. Config Extraction:
   • Trigger Analysis: Scans for "Custom Event" triggers and extracts the event name (e.g., login, purchase).
   • Variable Identification: Finds all Tags that fire on those triggers and recursively extracts any {{Data Layer Variable}} references within their parameters or HTML.
   • Mapping: Maps the identified variables to the corresponding event name.
3. Generator: Outputs a union type GtmDataLayerEvent where each member represents a specific GTM custom event and its required/optional variables.

graph TD
    API[GTM API v2] --> Triggers[Extract Custom Event Triggers]
    Triggers --> Tags[Identify Linked Tags]
    Tags --> Vars[Extract Data Layer Variables from Tags]
    Vars --> Union[Map to GtmDataLayerEvent Union Member]
    Union --> TS[Generate gtm.d.ts]

License

MIT