@ohto/nuxt-gtm-ecommerce

A Nuxt 3 module that extends @zadigetvoltaire/nuxt-gtm with a typed API for Google Analytics 4 (GA4) ecommerce events.

✔️ Easy-to-use helpers for all GA4 ecommerce events
✔️ Internally powered by useTrackEvent from @zadigetvoltaire/nuxt-gtm (runtime resolution)
✔️ TypeScript support with autocompletion
✔️ Works with JavaScript too
✔️ Enforces @zadigetvoltaire/nuxt-gtm as a dependency

🚀 Installation

npm install @zadigetvoltaire/nuxt-gtm @ohto/nuxt-gtm-ecommerce

⚙️ Setup

Important: Make sure to add @zadigetvoltaire/nuxt-gtm before this module in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    "@zadigetvoltaire/nuxt-gtm", // ← Must be added first
    "@ohto/nuxt-gtm-ecommerce",
  ],
  gtm: {
    id: "G-XXXXXXXXXX",
  },
});

Auto-imports Disabled?

If you have auto-imports disabled in your Nuxt config, the module will automatically fall back to using the direct gtm function. No additional configuration is needed - the module handles both scenarios gracefully.

📖 Usage

Injects $trackCommerceEvent into the Nuxt app.

<script setup>
const { $trackCommerceEvent } = useNuxtApp();

$trackCommerceEvent.addToCart({
  item_id: "SKU123",
  item_name: "Hat",
  price: 25,
  quantity: 1,
});
</script>

🛒 API Reference

| Method | Event | Description | | --------------------------------------------------- | ------------------- | -------------------------------------------------- | | viewItem(item) | view_item | Track when a user views a single product. | | viewItemList(items, listId?, listName?) | view_item_list | Track when a user views a list of products. | | selectItem(item, listId?, listName?) | select_item | Track when a user selects a product from a list. | | addToCart(item) | add_to_cart | Track when a product is added to the cart. | | removeFromCart(item) | remove_from_cart | Track when a product is removed from the cart. | | viewCart(items) | view_cart | Track when the user views their shopping cart. | | beginCheckout(items, coupon?) | begin_checkout | Track when checkout begins. | | addPaymentInfo(items, paymentType, coupon?) | add_payment_info | Track when payment info is added during checkout. | | addShippingInfo(items, shippingTier, coupon?) | add_shipping_info | Track when shipping info is added during checkout. | | purchase(order) | purchase | Track when a purchase is completed. | | refund(orderId, items?) | refund | Track when a purchase is refunded. |

🍳 Cookbook Examples

Add to Cart

<script setup>
const { $trackCommerceEvent } = useNuxtApp();

$trackCommerceEvent.addToCart({
  item_id: "SKU123",
  item_name: "Hat",
  price: 25,
  quantity: 1,
});
</script>

Purchase

<script setup>
const { $trackCommerceEvent } = useNuxtApp();

$trackCommerceEvent.purchase({
  id: "T12345",
  total: 100,
  currency: "USD",
  tax: 8,
  shipping: 5,
  items: [{ item_id: "SKU123", item_name: "Hat", price: 25, quantity: 2 }],
});
</script>

(See full cookbook for all event types.)

Dependencies:

• @zadigetvoltaire/nuxt-gtm (peer dependency, must be installed and configured)