@mars-stack/cli 0.2.0 → 0.2.2

package/template/.cursor/skills/configure-analytics/SKILL.md

@@ -0,0 +1,413 @@
+# Skill: Configure Analytics
+
+Set up analytics tracking with Vercel Analytics, PostHog, or Google Analytics in a MARS application.
+
+## When to Use
+
+Use this skill when the user asks to add analytics, tracking, page views, event tracking, Vercel Analytics, PostHog, Google Analytics, or a consent banner.
+
+## Prerequisites
+
+- Next.js app set up with the MARS template
+
+## Architecture
+
+MARS supports multiple analytics providers through a unified wrapper. The active provider is set in `appConfig.services.analytics`. All tracking calls go through a single `trackEvent` function, making it easy to swap providers.
+
+Supported providers:
+- `vercel` — Vercel Analytics + Web Vitals (zero-config for Vercel deployments)
+- `posthog` — PostHog (self-hostable, feature flags, session replay)
+- `google` — Google Analytics 4 (gtag.js)
+- `none` — disabled (default)
+
+## Step 1: Configuration
+
+```typescript
+// src/config/app.config.ts
+services: {
+  analytics: {
+    provider: 'none' as 'vercel' | 'posthog' | 'google' | 'none',
+    enableInDevelopment: false,
+  },
+},
+```
+
+## Step 2: Install Provider SDK
+
+**Vercel Analytics:**
+```bash
+yarn add @vercel/analytics @vercel/speed-insights
+```
+
+**PostHog:**
+```bash
+yarn add posthog-js
+```
+
+**Google Analytics:**
+No package needed — uses the gtag.js script tag.
+
+## Step 3: Environment Variables
+
+**Vercel Analytics:**
+No env vars needed — auto-configured on Vercel deployments.
+
+**PostHog:**
+```bash
+NEXT_PUBLIC_POSTHOG_KEY="phc_your-project-key"
+NEXT_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"
+```
+
+**Google Analytics:**
+```bash
+NEXT_PUBLIC_GA_MEASUREMENT_ID="G-XXXXXXXXXX"
+```
+
+## Step 4: Analytics Provider Component
+
+```typescript
+// src/lib/shared/components/providers/AnalyticsProvider.tsx
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname, useSearchParams } from 'next/navigation';
+import { appConfig } from '@/config/app.config';
+
+function usePageView() {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  useEffect(() => {
+    if (!pathname) return;
+
+    const url = searchParams?.toString()
+      ? `${pathname}?${searchParams.toString()}`
+      : pathname;
+
+    trackPageView(url);
+  }, [pathname, searchParams]);
+}
+
+export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
+  const provider = appConfig.services.analytics.provider;
+  const isDev = process.env.NODE_ENV === 'development';
+
+  if (provider === 'none' || (isDev && !appConfig.services.analytics.enableInDevelopment)) {
+    return <>{children}</>;
+  }
+
+  return (
+    <>
+      {provider === 'vercel' && <VercelAnalytics />}
+      {provider === 'posthog' && <PostHogProvider />}
+      {provider === 'google' && <GoogleAnalytics />}
+      <PageViewTracker />
+      {children}
+    </>
+  );
+}
+
+function PageViewTracker() {
+  usePageView();
+  return null;
+}
+```
+
+## Step 5: Vercel Analytics Setup
+
+```typescript
+// src/lib/shared/components/providers/analytics/VercelAnalytics.tsx
+'use client';
+
+import { Analytics } from '@vercel/analytics/react';
+import { SpeedInsights } from '@vercel/speed-insights/next';
+
+export function VercelAnalytics() {
+  return (
+    <>
+      <Analytics />
+      <SpeedInsights />
+    </>
+  );
+}
+```
+
+## Step 6: PostHog Setup
+
+```typescript
+// src/lib/shared/components/providers/analytics/PostHogProvider.tsx
+'use client';
+
+import posthog from 'posthog-js';
+import { PostHogProvider as PHProvider } from 'posthog-js/react';
+import { useEffect, useState } from 'react';
+
+export function PostHogProvider({ children }: { children?: React.ReactNode }) {
+  const [initialized, setInitialized] = useState(false);
+
+  useEffect(() => {
+    const key = process.env.NEXT_PUBLIC_POSTHOG_KEY;
+    const host = process.env.NEXT_PUBLIC_POSTHOG_HOST;
+
+    if (!key) {
+      console.warn('PostHog: NEXT_PUBLIC_POSTHOG_KEY is not set');
+      return;
+    }
+
+    posthog.init(key, {
+      api_host: host || 'https://us.i.posthog.com',
+      person_profiles: 'identified_only',
+      capture_pageview: false, // We handle this manually for SPA navigation
+      capture_pageleave: true,
+    });
+
+    setInitialized(true);
+  }, []);
+
+  if (!initialized) return <>{children}</>;
+
+  return <PHProvider client={posthog}>{children}</PHProvider>;
+}
+```
+
+## Step 7: Google Analytics Setup
+
+```typescript
+// src/lib/shared/components/providers/analytics/GoogleAnalytics.tsx
+'use client';
+
+import Script from 'next/script';
+
+export function GoogleAnalytics() {
+  const measurementId = process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID;
+
+  if (!measurementId) {
+    console.warn('Google Analytics: NEXT_PUBLIC_GA_MEASUREMENT_ID is not set');
+    return null;
+  }
+
+  return (
+    <>
+      <Script
+        strategy="afterInteractive"
+        src={`https://www.googletagmanager.com/gtag/js?id=${measurementId}`}
+      />
+      <Script
+        id="google-analytics"
+        strategy="afterInteractive"
+        dangerouslySetInnerHTML={{
+          __html: `
+            window.dataLayer = window.dataLayer || [];
+            function gtag(){dataLayer.push(arguments);}
+            gtag('js', new Date());
+            gtag('config', '${measurementId}', {
+              page_path: window.location.pathname,
+            });
+          `,
+        }}
+      />
+    </>
+  );
+}
+```
+
+## Step 8: Unified Tracking API
+
+```typescript
+// src/lib/shared/utils/analytics.ts
+import { appConfig } from '@/config/app.config';
+
+export function trackPageView(url: string) {
+  const provider = appConfig.services.analytics.provider;
+
+  switch (provider) {
+    case 'posthog': {
+      const posthog = (window as any).posthog;
+      posthog?.capture('$pageview', { $current_url: url });
+      break;
+    }
+    case 'google': {
+      const gtag = (window as any).gtag;
+      gtag?.('config', process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID, { page_path: url });
+      break;
+    }
+    case 'vercel':
+      // Vercel Analytics handles page views automatically
+      break;
+  }
+}
+
+export function trackEvent(
+  eventName: string,
+  properties?: Record<string, string | number | boolean>,
+) {
+  const provider = appConfig.services.analytics.provider;
+
+  if (process.env.NODE_ENV === 'development' && !appConfig.services.analytics.enableInDevelopment) {
+    console.debug(`[analytics] ${eventName}`, properties);
+    return;
+  }
+
+  switch (provider) {
+    case 'posthog': {
+      const posthog = (window as any).posthog;
+      posthog?.capture(eventName, properties);
+      break;
+    }
+    case 'google': {
+      const gtag = (window as any).gtag;
+      gtag?.('event', eventName, properties);
+      break;
+    }
+    case 'vercel': {
+      // Vercel Analytics custom events via @vercel/analytics
+      import('@vercel/analytics').then(({ track }) => track(eventName, properties));
+      break;
+    }
+  }
+}
+
+export function identifyUser(userId: string, traits?: Record<string, string>) {
+  const provider = appConfig.services.analytics.provider;
+
+  switch (provider) {
+    case 'posthog': {
+      const posthog = (window as any).posthog;
+      posthog?.identify(userId, traits);
+      break;
+    }
+    case 'google': {
+      const gtag = (window as any).gtag;
+      gtag?.('set', { user_id: userId, ...traits });
+      break;
+    }
+  }
+}
+```
+
+## Step 9: Consent Banner
+
+```typescript
+// src/lib/shared/components/patterns/ConsentBanner.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+
+const CONSENT_KEY = 'mars-analytics-consent';
+
+export function ConsentBanner() {
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    const consent = localStorage.getItem(CONSENT_KEY);
+    if (consent === null) setVisible(true);
+  }, []);
+
+  function handleAccept() {
+    localStorage.setItem(CONSENT_KEY, 'granted');
+    setVisible(false);
+    window.location.reload();
+  }
+
+  function handleDecline() {
+    localStorage.setItem(CONSENT_KEY, 'denied');
+    setVisible(false);
+  }
+
+  if (!visible) return null;
+
+  return (
+    <div className="fixed bottom-0 left-0 right-0 z-50 border-t border-border-primary bg-surface-primary p-4 shadow-lg">
+      <div className="mx-auto flex max-w-4xl items-center justify-between gap-4">
+        <p className="text-sm text-content-secondary">
+          We use cookies and analytics to improve your experience. You can opt out at any time.
+        </p>
+        <div className="flex shrink-0 gap-2">
+          <button
+            onClick={handleDecline}
+            className="rounded-md px-4 py-2 text-sm text-content-secondary hover:text-content-primary"
+          >
+            Decline
+          </button>
+          <button
+            onClick={handleAccept}
+            className="rounded-md bg-interactive-primary px-4 py-2 text-sm text-white hover:bg-interactive-primary-hover"
+          >
+            Accept
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+Update the `AnalyticsProvider` to check consent:
+
+```typescript
+const consent = typeof window !== 'undefined' ? localStorage.getItem('mars-analytics-consent') : null;
+if (consent === 'denied') return <>{children}</>;
+```
+
+## Step 10: Add to Root Layout
+
+```typescript
+// src/app/layout.tsx
+import { AnalyticsProvider } from '@/lib/shared/components/providers/AnalyticsProvider';
+import { ConsentBanner } from '@/lib/shared/components/patterns/ConsentBanner';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <AnalyticsProvider>
+          {children}
+          <ConsentBanner />
+        </AnalyticsProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Usage Examples
+
+Track a custom event anywhere in client code:
+
+```typescript
+import { trackEvent } from '@/lib/shared/utils/analytics';
+
+trackEvent('button_clicked', { button: 'upgrade', plan: 'pro' });
+trackEvent('feature_used', { feature: 'export', format: 'csv' });
+```
+
+Identify a user after login:
+
+```typescript
+import { identifyUser } from '@/lib/shared/utils/analytics';
+
+identifyUser(session.userId, { email: session.email, plan: 'free' });
+```
+
+## Testing
+
+1. Set provider to `'none'` — verify no scripts load and events log to console in dev.
+2. Set provider to `'vercel'` — deploy to Vercel, check the Analytics dashboard.
+3. Set provider to `'posthog'` — verify events appear in PostHog project.
+4. Set provider to `'google'` — check Google Analytics Realtime view.
+5. Decline consent — verify no tracking scripts load.
+6. Accept consent — verify tracking resumes after reload.
+7. Navigate between pages — verify page views are tracked.
+
+## Checklist
+
+- [ ] Analytics provider set in `appConfig.services.analytics.provider`
+- [ ] Provider SDK installed (Vercel, PostHog, or gtag)
+- [ ] Environment variables set for the chosen provider
+- [ ] `AnalyticsProvider` wraps the app in root layout
+- [ ] Unified `trackEvent`, `trackPageView`, and `identifyUser` functions
+- [ ] Page view tracking on SPA navigation
+- [ ] Consent banner with `localStorage` persistence
+- [ ] Analytics disabled when consent is denied
+- [ ] Development mode logging to console
+- [ ] No tracking in development unless `enableInDevelopment` is set