data-gtm-id Codemod: 4-Command GTM Tracking Workflow

You just finished building the app. The UI works, the flows are solid, and you are ready to open it to real users. Then the product question arrives: "Can we track which buttons people are clicking?"

The answer is yes — but if you reach for Google Tag Manager and start writing CSS selectors against your component classes, you are building on sand. Class names change. Layouts get refactored. Someone cleans up unused styles without thinking about analytics, and your tracking silently breaks with no warning.

The stable approach is to add a dedicated data-gtm-id attribute to every meaningful interactive element in your codebase. GTM targets those attributes instead of fragile DOM paths. The attribute is explicit, human-readable, independent of styling, and survives refactors cleanly.

The problem is doing this across hundreds of files. You are not going to do it by hand. This guide walks through a repeatable codemod workflow that audits your interactive surface, adds automatically using a proper AST transform, and exports a reference CSV and TXT file for your analytics team — all in four commands.

Component	Slug
`Button` / `button`	`button`
`Link` / `a`	`link`
`SidebarTrigger`	`sidebar-trigger`
`SidebarMenuButton`	`sidebar-menu-button`
`LogoutButton`	`logout-button`

// File: scripts/audit-pisarna-interactions.cjs

/* eslint-disable @typescript-eslint/no-require-imports */
const fs = require("fs");
const path = require("path");

const ROOTS = [
  "src/app/(frontend)/[locale]/[tenant]/pisarna",
  "src/components/office",
];

const TARGET_PATTERNS = [
  { name: "Button",                    search: "<Button" },
  { name: "Native button",             search: "<button" },
  { name: "Next Link",                 search: "<Link" },
  { name: "Native link",               search: "<a " },
  { name: "DialogTrigger",             search: "<DialogTrigger" },
  { name: "SheetTrigger",              search: "<SheetTrigger" },
  { name: "TabsTrigger",               search: "<TabsTrigger" },
  { name: "SidebarTrigger",            search: "<SidebarTrigger" },
  { name: "SidebarMenuButton",         search: "<SidebarMenuButton" },
  { name: "SidebarMenuSubButton",      search: "<SidebarMenuSubButton" },
  { name: "LogoutButton",              search: "<LogoutButton" },
  { name: "AlertDialogTrigger",        search: "<AlertDialogTrigger" },
  { name: "SelectItem",                search: "<SelectItem" },
  { name: "DropdownMenuCheckboxItem",  search: "<DropdownMenuCheckboxItem" },
];

function walk(dirPath, files = []) {
  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
  for (const entry of entries) {
    const nextPath = path.join(dirPath, entry.name);
    if (entry.isDirectory()) { walk(nextPath, files); continue; }
    if (entry.isFile() && /\.(tsx|jsx)$/.test(entry.name)) { files.push(nextPath); }
  }
  return files;
}

function getMatchesForFile(filePath) {
  const source = fs.readFileSync(filePath, "utf8");
  const lines = source.split(/\r?\n/);
  const matches = [];
  lines.forEach((line, index) => {
    for (const pattern of TARGET_PATTERNS) {
      if (line.includes(pattern.search)) {
        matches.push({ line: index + 1, pattern: pattern.name, code: line.trim() });
      }
    }
  });
  return matches;
}

function main() {
  const files = ROOTS.flatMap((rootPath) => walk(rootPath));
  const totals = new Map(TARGET_PATTERNS.map((p) => [p.name, 0]));
  const perFile = [];

  for (const filePath of files) {
    const matches = getMatchesForFile(filePath);
    if (matches.length === 0) continue;
    perFile.push({ filePath, matches });
    for (const match of matches) {
      totals.set(match.pattern, (totals.get(match.pattern) || 0) + 1);
    }
  }

  console.log("# Pisarna Interaction Audit\n");
  console.log(`Files scanned: ${files.length}`);
  console.log(`Files with matches: ${perFile.length}\n`);
  console.log("## Summary");
  for (const pattern of TARGET_PATTERNS) {
    console.log(`- ${pattern.name}: ${totals.get(pattern.name) || 0}`);
  }
  console.log("\n## Files");
  for (const entry of perFile) {
    console.log(`- ${entry.filePath}`);
    for (const match of entry.matches) {
      console.log(`  - L${match.line} ${match.pattern}: ${match.code}`);
    }
  }
}

main();

// File: scripts/add-gtm-id.cjs

/* eslint-disable @typescript-eslint/no-require-imports */
const path = require("path");
const { transliterate } = require("transliteration");

const TARGET_COMPONENTS = new Set([
  "button", "a", "Button", "IconButton", "Link",
  "DialogTrigger", "SheetTrigger", "TabsTrigger",
  "SidebarTrigger", "SidebarMenuButton", "SidebarMenuSubButton", "LogoutButton",
]);

const INTERACTIVE_CHILD_COMPONENTS = new Set([
  "button", "a", "Button", "IconButton", "Link", "SidebarTrigger", "LogoutButton",
]);

const TEXT_ATTRIBUTE_CANDIDATES  = ["aria-label", "title", "tooltip", "label", "placeholder"];
const VALUE_ATTRIBUTE_CANDIDATES = ["href", "value", "id", "name"];
const SELF_NAMED_FALLBACKS = new Map([
  ["SidebarTrigger", "toggle-sidebar"],
  ["LogoutButton",   "logout"],
]);

function getElementName(name) {
  if (!name) return null;
  if (name.type === "JSXIdentifier")      return name.name;
  if (name.type === "JSXMemberExpression") return getElementName(name.property);
  if (name.type === "JSXNamespacedName")  return name.name?.name ?? null;
  return null;
}

function hasAttribute(openingElement, attrName) {
  return openingElement.attributes.some(
    (attr) => attr.type === "JSXAttribute" && attr.name?.name === attrName,
  );
}

function getAttribute(openingElement, attrName) {
  return openingElement.attributes.find(
    (attr) => attr.type === "JSXAttribute" && attr.name?.name === attrName,
  ) ?? null;
}

function isTruthyAttribute(openingElement, attrName) {
  const attr = getAttribute(openingElement, attrName);
  if (!attr) return false;
  if (attr.value == null) return true;
  const value = getAttributeValue(attr);
  return value === "" || value === "true" || value === true;
}

function getAttributeValue(attr) {
  if (!attr?.value) return "";
  if (attr.value.type === "StringLiteral") return attr.value.value;
  if (attr.value.type === "Literal" && typeof attr.value.value === "string") return attr.value.value;
  if (attr.value.type === "JSXExpressionContainer") return getExpressionValue(attr.value.expression);
  return "";
}

function getExpressionValue(expression) {
  if (!expression) return "";
  switch (expression.type) {
    case "StringLiteral":  return expression.value;
    case "Literal":        return typeof expression.value === "string" ? expression.value : "";
    case "TemplateLiteral":
      if (expression.expressions.length === 0)
        return expression.quasis.map((q) => q.value.cooked ?? "").join("");
      return expression.quasis.map((q) => q.value.cooked ?? "").join(" ").trim();
    case "Identifier":         return expression.name;
    case "MemberExpression":   return flattenMemberExpression(expression);
    case "ConditionalExpression":
      return [getExpressionValue(expression.consequent), getExpressionValue(expression.alternate)]
        .filter(Boolean).join(" ");
    case "LogicalExpression":
      return [getExpressionValue(expression.left), getExpressionValue(expression.right)]
        .filter(Boolean).join(" ");
    default: return "";
  }
}

function flattenMemberExpression(expression) {
  if (!expression) return "";
  const object   = expression.object.type === "Identifier" ? expression.object.name
    : expression.object.type === "MemberExpression" ? flattenMemberExpression(expression.object) : "";
  const property = expression.property.type === "Identifier" ? expression.property.name
    : expression.property.type === "Literal" && typeof expression.property.value === "string"
      ? expression.property.value : "";
  return [object, property].filter(Boolean).join("-");
}

function slugify(value) {
  return transliterate(String(value || ""))
    .replace(/\.[^.]+$/, "")
    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-|-$/g, "");
}

function getFileSlug(filePath) {
  const normalizedPath = filePath.split(path.sep).join("/");
  const relative =
    normalizedPath.includes("src/app/(frontend)/[locale]/[tenant]/pisarna/")
      ? normalizedPath.split("src/app/(frontend)/[locale]/[tenant]/pisarna/")[1]
      : normalizedPath.includes("src/components/office/")
        ? normalizedPath.split("src/components/office/")[1]
        : path.basename(normalizedPath);
  return slugify(relative.replace(/\.[^.]+$/, "")) || "unknown-file";
}

function getElementSlug(elementName) {
  if (elementName === "button"  || elementName === "Button")  return "button";
  if (elementName === "a"       || elementName === "Link")    return "link";
  if (elementName === "IconButton")             return "icon-button";
  if (elementName === "SidebarTrigger")         return "sidebar-trigger";
  if (elementName === "SidebarMenuButton")      return "sidebar-menu-button";
  if (elementName === "SidebarMenuSubButton")   return "sidebar-menu-sub-button";
  if (elementName === "LogoutButton")           return "logout-button";
  return slugify(elementName);
}

function getTextFromChildren(children = []) {
  return children
    .map((child) => {
      if (child.type === "JSXText")               return child.value;
      if (child.type === "JSXExpressionContainer") return getExpressionValue(child.expression);
      if (child.type === "JSXElement")             return getTextFromChildren(child.children);
      if (child.type === "JSXFragment")            return getTextFromChildren(child.children);
      return "";
    })
    .join(" ")
    .replace(/\s+/g, " ")
    .trim();
}

function getBestValueSlug(jsxElement, openingElement, elementName) {
  const childText = getTextFromChildren(jsxElement.children);
  if (childText) return slugify(childText);

  for (const attrName of TEXT_ATTRIBUTE_CANDIDATES) {
    const value = getAttributeValue(getAttribute(openingElement, attrName));
    if (value) return slugify(value);
  }
  for (const attrName of VALUE_ATTRIBUTE_CANDIDATES) {
    const value = getAttributeValue(getAttribute(openingElement, attrName));
    if (value) return slugify(value);
  }
  if (SELF_NAMED_FALLBACKS.has(elementName)) return SELF_NAMED_FALLBACKS.get(elementName);

  const typeValue = getAttributeValue(getAttribute(openingElement, "type"));
  if (typeValue) return slugify(typeValue);

  return "unknown";
}

function getFirstInteractiveChild(jsxElement) {
  return jsxElement.children.find((child) => {
    if (child.type !== "JSXElement") return false;
    return INTERACTIVE_CHILD_COMPONENTS.has(getElementName(child.openingElement.name));
  }) ?? null;
}

module.exports = function transformer(fileInfo, api) {
  const j        = api.jscodeshift;
  const root     = j(fileInfo.source);
  const fileSlug = getFileSlug(fileInfo.path);
  const counters = new Map();

  root.find(j.JSXElement).forEach((jsxPath) => {
    const opening     = jsxPath.node.openingElement;
    const elementName = getElementName(opening.name);

    if (!TARGET_COMPONENTS.has(elementName))    return;
    if (hasAttribute(opening, "data-gtm-id"))   return;

    if (isTruthyAttribute(opening, "asChild")) {
      if (getFirstInteractiveChild(jsxPath.node)) return;
    }

    const elementSlug = getElementSlug(elementName);
    const valueSlug   = getBestValueSlug(jsxPath.node, opening, elementName) || "unknown";
    const baseId      = `${fileSlug}-${elementSlug}-${valueSlug}`;
    const count       = counters.get(baseId) || 0;
    counters.set(baseId, count + 1);
    const finalId     = count === 0 ? baseId : `${baseId}-${count + 1}`;

    opening.attributes.push(
      j.jsxAttribute(j.jsxIdentifier("data-gtm-id"), j.stringLiteral(finalId)),
    );
  });

  return root.toSource({ quote: "double", trailingComma: true });
};

module.exports.parser = "tsx";

// File: scripts/export-pisarna-gtm-ids.cjs

/* eslint-disable @typescript-eslint/no-require-imports */
const fs   = require("fs");
const path = require("path");

const ROOTS = [
  "src/app/(frontend)/[locale]/[tenant]/pisarna",
  "src/components/office",
];

const OUTPUT_DIR = "artifacts/gtm";
const CSV_PATH   = path.join(OUTPUT_DIR, "pisarna-gtm-ids.csv");
const TXT_PATH   = path.join(OUTPUT_DIR, "pisarna-gtm-ids.txt");

function walk(dirPath, files = []) {
  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
  for (const entry of entries) {
    const nextPath = path.join(dirPath, entry.name);
    if (entry.isDirectory()) { walk(nextPath, files); continue; }
    if (entry.isFile() && /\.(tsx|jsx)$/.test(entry.name)) { files.push(nextPath); }
  }
  return files;
}

function csvEscape(value) {
  return `"${String(value ?? "").replace(/"/g, '""')}"`;
}

function extractIds(filePath) {
  const source = fs.readFileSync(filePath, "utf8");
  const lines  = source.split(/\r?\n/);
  const rows   = [];
  lines.forEach((line, index) => {
    for (const match of [...line.matchAll(/data-gtm-id="([^"]+)"/g)]) {
      rows.push({ id: match[1], file: filePath, line: index + 1, code: line.trim() });
    }
  });
  return rows;
}

function main() {
  const files = ROOTS.flatMap((r) => walk(r)).sort();
  const rows  = files.flatMap((f) => extractIds(f));
  rows.sort((a, b) => {
    if (a.id   !== b.id)   return a.id.localeCompare(b.id);
    if (a.file !== b.file) return a.file.localeCompare(b.file);
    return a.line - b.line;
  });

  fs.mkdirSync(OUTPUT_DIR, { recursive: true });

  // CSV
  const header  = ["id", "file", "line", "code"];
  const csvRows = [
    header.map(csvEscape).join(","),
    ...rows.map((r) => [r.id, r.file, r.line, r.code].map(csvEscape).join(",")),
  ].join("\n");
  fs.writeFileSync(CSV_PATH, `${csvRows}\n`, "utf8");

  // TXT — grouped by file
  const grouped = new Map();
  for (const row of rows) {
    if (!grouped.has(row.file)) grouped.set(row.file, []);
    grouped.get(row.file).push(row);
  }
  const chunks = [];
  for (const [file, fileRows] of grouped.entries()) {
    chunks.push(file);
    for (const row of fileRows) chunks.push(`  L${row.line}  ${row.id}`);
    chunks.push("");
  }
  fs.writeFileSync(TXT_PATH, `${chunks.join("\n").trim()}\n`, "utf8");

  console.log(`Exported ${rows.length} GTM IDs.`);
  console.log(`CSV: ${CSV_PATH}`);
  console.log(`TXT: ${TXT_PATH}`);
}

main();

data-gtm-id Codemod: 4-Command GTM Tracking Workflow

⚡ Next.js Implementation Guides

Frequently Asked Questions

Comments

No comments yet

Why CSS Selectors Break and Why You Should Stop Using Them for Analytics

Why not just use `id=""`?

The Naming Convention

The Three Scripts

Script 1: Audit Your Interactive Surface

Script 2: The Codemod

After the Run: Cleaning Up `unknown` IDs

Script 3: Export the Reference Files

Supporting Custom Components

What You Can Answer After This

Known Limitations

The Full Workflow in Order

Extending to Other App Areas

FAQ

Conclusion