GA4 Analytics in Next.js

Install

npm install @next/third-parties

Environment

NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

Optional — app works without it. Never commit real IDs to public repos if policy requires secrets (usually GA ID is public).

export function getPublicGaId(): string | undefined {
  return process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID;
}

Root layout wiring

import { GoogleAnalytics } from "@next/third-parties/google";
import { getPublicGaId } from "@/lib/analytics-config";

export default function RootLayout({ children }) {
  const gaId = getPublicGaId();
  return (
    <html>
      <body>
        {children}
        {gaId ? <GoogleAnalytics gaId={gaId} /> : null}
      </body>
    </html>
  );
}

Loads gtag only when ID present — safe for local dev.

Typed event helper (lib/analytics.ts)

export type AnalyticsEvent =
  | "page_view"
  | "cta_click"
  | "form_submit"
  | "form_submit_success"
  | "form_submit_error";

declare global {
  interface Window {
    gtag?: (...args: unknown[]) => void;
  }
}

export function trackEvent(
  event: AnalyticsEvent,
  params?: Record<string, string | number | boolean | undefined>
) {
  if (typeof window === "undefined" || !window.gtag) return;
  const cleaned = params
    ? Object.fromEntries(Object.entries(params).filter(([, v]) => v !== undefined))
    : undefined;
  window.gtag("event", event, cleaned);
}

Extend AnalyticsEvent union as features ship — keeps naming consistent.

SPA page views (App Router)

GoogleAnalytics handles initial load. For client navigations, add a provider:

"use client";
import { usePathname, useSearchParams } from "next/navigation";
import { useEffect } from "react";
import { trackPageView } from "@/lib/analytics";

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    const url = pathname + (searchParams?.toString() ? `?${searchParams}` : "");
    trackPageView(url);
  }, [pathname, searchParams]);

  return <>{children}</>;
}

Wrap in layout inside <body>.

What to track

Use snake_case event names. Pass structured params (step, source, variant) not concatenated strings.

Client usage

<Button onClick={() => {
  trackEvent("cta_click", { location: "hero", label: "get_started" });
  router.push("/signup");
}}>
  Get Started
</Button>

Pick one tracking mechanism per element — either trackEvent() in onClick or data-analytics-* attributes with a delegated listener, not both (duplicate GA events).

Privacy / compliance

• Document analytics in privacy policy
• Consider cookie consent banner for EU (load GA after consent if required)
• Avoid PII in event params (no raw emails/names)
• Use GA4 data retention settings in admin console

Debugging

• GA4 DebugView (enable debug mode via Chrome extension or debug_mode: true param)
• Verify window.gtag exists after load
• Check ad blockers if events missing locally

Anti-patterns

• Importing gtag scripts manually when @next/third-parties exists
• Untyped string events scattered across codebase
• Tracking before consent when legally required
• Duplicate events from both trackEvent() and data-analytics-event on the same click