@vp-tw/nanostores-data-layer

A nanostores adapter for Google Tag Manager dataLayer. Reactively sync GTM dataLayer changes to a nanostores store.

Installation

npm install @vp-tw/nanostores-data-layer nanostores
# or
pnpm add @vp-tw/nanostores-data-layer nanostores
# or
yarn add @vp-tw/nanostores-data-layer nanostores

Usage

Processing All Events (Including Past)

Use subscribe() when you need to process events that were pushed before your code runs (e.g., GTM tags that fire on page load). The callback is executed immediately upon subscription:

import { $dataLayer } from "@vp-tw/nanostores-data-layer";

// Events already in dataLayer (e.g., pushed by GTM before your code runs)
window.dataLayer.push({ event: "gtm.js" });
window.dataLayer.push({ event: "page_view", page_path: "/home" });

// Callback runs IMMEDIATELY (even before any new push)
const unsubscribe = $dataLayer.subscribe((events, oldEvents) => {
  const newEvents = events.slice(oldEvents?.length ?? 0);
  newEvents.forEach((event) => {
    console.log("Event:", event);
  });
});
// Console: Event: { event: 'gtm.js' }           ← immediately!
// Console: Event: { event: 'page_view', ... }  ← immediately!

// Future pushes also trigger the callback
window.dataLayer.push({ event: "click" });
// Console: Event: { event: 'click' }

unsubscribe();

Processing Only New Events

Use listen() when you only care about future events. The callback is not executed immediately—it only fires when new events are pushed:

import { $dataLayer } from "@vp-tw/nanostores-data-layer";

// Events already in dataLayer
window.dataLayer.push({ event: "gtm.js" });
window.dataLayer.push({ event: "page_view", page_path: "/home" });

// Callback does NOT run immediately
const unlisten = $dataLayer.listen((events, oldEvents) => {
  const newEvents = events.slice(oldEvents?.length ?? 0);
  newEvents.forEach((event) => {
    console.log("Event:", event);
  });
});
// (no output)

// Only future pushes trigger the callback
window.dataLayer.push({ event: "click" });
// Console: Event: { event: 'click' }

unlisten();

Getting Current Value

import { $dataLayer } from "@vp-tw/nanostores-data-layer";

console.log($dataLayer.get()); // Current dataLayer contents

With React

import { useStore } from "@nanostores/react";
import { $dataLayer } from "@vp-tw/nanostores-data-layer";

function Analytics() {
  const dataLayer = useStore($dataLayer);

  return <pre>{JSON.stringify(dataLayer, null, 2)}</pre>;
}

With Vue

<script setup>
import { useStore } from "@nanostores/vue";
import { $dataLayer } from "@vp-tw/nanostores-data-layer";

const dataLayer = useStore($dataLayer);
</script>

<template>
  <pre>{{ dataLayer }}</pre>
</template>

How It Works

The library:

1. Initializes window.dataLayer if not present
2. Wraps the native push method to intercept all additions
3. Syncs changes to a readonly nanostores atom

The store is readonly (ReadableAtom) - you should push to window.dataLayer directly, and the store will automatically update.

SSR Support

The library safely handles server-side rendering. When window is undefined, the store returns an empty array and no errors are thrown.

TypeScript

Full TypeScript support is included. The DataLayer type is Array<unknown> by design, since GTM dataLayer can contain arbitrary data from various sources (GTM tags, third-party scripts, etc.).

import type { DataLayer } from "@vp-tw/nanostores-data-layer";

Type Safety with Runtime Validation

Since dataLayer contents are inherently dynamic, we recommend using runtime validation libraries like Zod or ArkType for type-safe event handling:

import type { DataLayer } from "@vp-tw/nanostores-data-layer";
import { $dataLayer } from "@vp-tw/nanostores-data-layer";
import { z } from "zod";

// Define your event schemas
const PageViewEvent = z.object({
  event: z.literal("page_view"),
  page_path: z.string(),
});

const PurchaseEvent = z.object({
  event: z.literal("purchase"),
  transaction_id: z.string(),
  value: z.number(),
});

const MyEvent = z.discriminatedUnion("event", [PageViewEvent, PurchaseEvent]);
type MyEvent = z.infer<typeof MyEvent>;

// Type-safe event processing
$dataLayer.subscribe((events, oldEvents) => {
  const newEvents = events.slice(oldEvents?.length ?? 0);

  for (const item of newEvents) {
    const result = MyEvent.safeParse(item);
    if (result.success) {
      // result.data is fully typed as MyEvent
      switch (result.data.event) {
        case "page_view":
          console.log("Page view:", result.data.page_path);
          break;
        case "purchase":
          console.log("Purchase:", result.data.transaction_id, result.data.value);
          break;
      }
    }
  }
});

Generic Type Parameter

For simpler cases where you control all dataLayer inputs, you can use the generic type parameter for type assertions:

import type { DataLayer } from "@vp-tw/nanostores-data-layer";

interface MyEvent {
  event: string;
  [key: string]: unknown;
}

// Type assertion (use with caution - no runtime validation)
const events = $dataLayer.get() as DataLayer<MyEvent>;

License

MIT

Copyright (c) 2026 ViPro [email protected] (https://vdustr.dev)