add-analytics

Google Analytics 4 Setup Skill

You are setting up Google Analytics 4 (GA4) for a project. Follow this comprehensive guide to add analytics properly.

Arguments

Parse the following from $ARGUMENTS:

• Measurement ID: Format G-XXXXXXXXXX (required, ask if not provided)
• --events: Include custom event tracking helpers
• --consent: Include cookie consent integration
• --debug: Enable debug mode for development

Step 1: Detect Project Type

Scan the project to determine the framework/setup:

Priority detection order:
1. next.config.js/ts → Next.js
2. nuxt.config.js/ts → Nuxt.js
3. astro.config.mjs → Astro
4. svelte.config.js → SvelteKit
5. remix.config.js → Remix
6. gatsby-config.js → Gatsby
7. vite.config.js + src/App.vue → Vue + Vite
8. vite.config.js + src/App.tsx → React + Vite
9. angular.json → Angular
10. package.json with "react-scripts" → Create React App
11. index.html only → Plain HTML
12. _app.tsx/jsx → Next.js (App Router check: app/ directory)

Also check for:

• TypeScript usage (tsconfig.json)
• Existing analytics (search for gtag, GA, analytics)
• Package manager (pnpm-lock.yaml, yarn.lock, package-lock.json)

Step 2: Validate Measurement ID

The Measurement ID must:

• Start with G- (GA4 format)
• Be followed by exactly 10 alphanumeric characters
• Example: G-ABC1234567

If the user provides a UA- ID, inform them:

"You provided a Universal Analytics ID (UA-). GA4 uses Measurement IDs starting with 'G-'. Universal Analytics was sunset in July 2024. You'll need to create a GA4 property at analytics.google.com"

Step 3: Implementation by Framework

Next.js (App Router - app/ directory)

Create app/layout.tsx modification or create components/GoogleAnalytics.tsx:

// components/GoogleAnalytics.tsx
'use client'

import Script from 'next/script'

interface GoogleAnalyticsProps {
  measurementId: string
}

export function GoogleAnalytics({ measurementId }: GoogleAnalyticsProps) {
  return (
    <>
      <Script
        src={`https://www.googletagmanager.com/gtag/js?id=${measurementId}`}
        strategy="afterInteractive"
      />
      <Script id="google-analytics" strategy="afterInteractive">
        {`
          window.dataLayer = window.dataLayer || [];
          function gtag(){dataLayer.push(arguments);}
          gtag('js', new Date());
          gtag('config', '${measurementId}');
        `}
      </Script>
    </>
  )
}