Stop Messing Up GA4 Events: A Type-Safe Analytics Library for React & Next.js

Google Analytics 4 (GA4) is powerful — but let’s be honest, the default gtag snippets get messy fast. That’s why I built a library @connectaryal/google-analytics — a type-safe, developer-friendly GA4 wrapper for React and Next.js.
No more guesswork, no more typos. Just clean analytics tracking. 🚀

✨ What You Get

✅ Easy initialization with a singleton instance
✅ Type-safe events (no more “pageveiw” mistakes 🙃)
✅ Ready-to-use methods for interaction, auth, and e-commerce
✅ Debug mode for development
✅ Works in both React & Next.js

🔑 Step 1:Create Your Google Analytics 4 Property

Before writing any code, set up your GA4 property:

1. Visit Google Analytics.
2. Click Admin (bottom left) > Create Property.
3. Name your property, timezone/currency, and click Next.
4. Add a new Web data stream for your site.
5. Copy your Measurement ID (looks like G-XXXXXXXXXX).

📦 Step 2: Install the npm Package

Skip the manual gtag script and use a robust, type-safe library:

npm install @connectaryal/google-analytics
# or
yarn add @connectaryal/google-analytics
# or
pnpm add @connectaryal/google-analytics

See the package on npm: @connectaryal/google-analytics

⚙️ Step 3: Initialize Analytics

The library uses a context provider for global React integration. Wrap your app at the highest level:

import { GAProvider } from "@connectaryal/google-analytics";

function App() {
  return (
    <GAProvider config={{ measurementId: "G-XXXXXXXXXX" }}>
      <YourApp />
    </GAProvider>
  );
}

Pro Tip: For Next.js, wrap your custom App or RootLayout component.

📄 Step 4: Track Events: Page Interaction, Engagement, E-commerce

📄 Track a Page View

import {
  EventCategory,
  trackPage,
} from '@connectaryal/google-analytics';

const { trackPage } = useGoogleAnalytics();

trackPage(); // auto detects

🎯 Custom Engagement & Conversion

import {
  EventCategory,
  useGoogleAnalytics,
} from '@connectaryal/google-analytics';

const { trackCustomEvent } = useGoogleAnalytics();

trackCustomEvent({
    name: "video_play",
    category: EventCategory.INTERACTION,
    params: { video_title: "Intro Demo", video_duration: 120 },
});

🛒 E-commerce Tracking

import { useGAEcommerce } from "@connectaryal/google-analytics";

const { trackCart, trackPurchase } = useGAEcommerce();

trackCart("add_to_cart", [
  { item_id: "SKU123", item_name: "Wireless Headphones", price: 99.99, quantity: 1 }
], 99.99);

trackPurchase("ORDER123", 199.98, [
  { item_id: "SKU123", item_name: "Wireless Headphones", price: 99.99, quantity: 2 }
]);

🔍 Step 5. Advanced Tracking: Validated, Typed & Error-Proof

With the GATracker class (used internally, or for advanced users):

• Every method checks for empty arrays, missing values, or invalid input.
• All events are type-checked with TypeScript.
• Debug mode logs warnings and errors clearly.

Example: Handling Validation

const tracker = new GATracker({ measurementId: "G-XXXXXXXXXX", currency: "USD", debug: true });

try {
  await tracker.trackCart({
    action: "add_to_cart",
    items: [],
    value: 99.99
  });
} catch (e) {
  // Will throw: "GA4: Cannot track add_to_cart with empty items"
  console.error(e);
}

🛠️ Step 6: Debug Mode

Turn on debugging to see event logs:

const tracker = new GATracker({`
  measurementId: "G-XXXXXXXXXX",`
  debug: true,`
});

Now you’ll see every event in the console 🎉

✅ Why Type Safety Matters

• No typos → “pageveiw” won’t even compile
• Strict params → keeps you aligned with GA schema
• Reusable methods → no more raw gtag("event", …) everywhere

📖 Full API Reference

Here’s everything included in the package:

Full API Reference

Why Use Type-Safe Analytics?

• No more silent failures: Type errors and validation mean you catch mistakes early.
• Enterprise-grade: Handles all GA4 e-commerce, engagement, and conversion flows.
• Debugging is simple: Errors and warnings are clear, actionable, and logged only in dev mode.

Final Thoughts

Modern analytics isn’t just about tracking everything—it’s about tracking the right things, with clean, validated code you can trust. By starting with a GA4 property and using a type-safe, React-optimized library, your data is actionable and your integration is future-proof.

Ready to track smarter?

👉 Found issue or want to contribute.