@launch77-shared/plugin-analytics-web 0.0.1

package/README.md

@@ -0,0 +1,39 @@
+# AnalyticsWeb Plugin
+
+Launch77 plugin for analytics-web
+
+## Installation
+
+```bash
+launch77 plugin:install analytics-web
+```
+
+## Usage
+
+After installation, the plugin will:
+
+- TODO: Describe what the plugin does
+- TODO: List any files created or modified
+- TODO: Explain configuration options
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm run typecheck
+```
+
+## Template Files
+
+The `templates/` directory contains files that will be copied to the target application when this plugin is installed. Add any template files your plugin needs here.
+
+## License
+
+UNLICENSED

package/dist/generator.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+
+// src/generator.ts
+import * as path2 from "path";
+import chalk from "chalk";
+import { StandardGenerator } from "@launch77/plugin-runtime";
+
+// src/utils/layout-modifier.ts
+import fs from "fs/promises";
+async function wrapWithAnalyticsProvider(layoutPath) {
+  try {
+    const fileExists = await fs.access(layoutPath).then(() => true).catch(() => false);
+    if (!fileExists) {
+      return {
+        success: false,
+        error: `File not found: ${layoutPath}`
+      };
+    }
+    let content = await fs.readFile(layoutPath, "utf-8");
+    if (content.includes("AnalyticsProvider") || content.includes("@launch77-shared/lib-analytics-web")) {
+      return {
+        success: true,
+        alreadyExists: true
+      };
+    }
+    const importStatement = `import { AnalyticsProvider, CookieConsent } from '@launch77-shared/lib-analytics-web'
+`;
+    const lines = content.split("\n");
+    let lastImportIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].trim().startsWith("import ") || lines[i].trim().startsWith("import{")) {
+        lastImportIndex = i;
+      }
+    }
+    if (lastImportIndex !== -1) {
+      lines.splice(lastImportIndex + 1, 0, importStatement);
+    } else {
+      let insertIndex = 0;
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes("'use client'") || lines[i].includes("'use server'") || lines[i].includes('"use client"') || lines[i].includes('"use server"')) {
+          insertIndex = i + 1;
+          break;
+        }
+      }
+      lines.splice(insertIndex, 0, "", importStatement);
+    }
+    content = lines.join("\n");
+    const childrenRegex = /(<html[^>]*>[\s\S]*?)(\{children\})([\s\S]*?<\/html>)/;
+    const match = content.match(childrenRegex);
+    if (!match) {
+      return {
+        success: false,
+        error: "Could not find {children} in layout.tsx"
+      };
+    }
+    const _beforeChildren = match[1];
+    const childrenPlaceholder = match[2];
+    const _afterChildren = match[3];
+    const childrenLine = content.split("\n").find((line) => line.includes("{children}"));
+    const indentMatch = childrenLine?.match(/^(\s+)/);
+    const baseIndent = indentMatch ? indentMatch[1] : "        ";
+    const wrappedChildren = `<AnalyticsProvider
+${baseIndent}  gtmId={process.env.NEXT_PUBLIC_GTM_ID}
+${baseIndent}  posthogKey={process.env.NEXT_PUBLIC_POSTHOG_KEY}
+${baseIndent}>
+${baseIndent}  ${childrenPlaceholder}
+${baseIndent}  <CookieConsent />
+${baseIndent}</AnalyticsProvider>`;
+    content = content.replace(childrenRegex, `$1${wrappedChildren}$3`);
+    await fs.writeFile(layoutPath, content, "utf-8");
+    return {
+      success: true
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/utils/env-modifier.ts
+import fs2 from "fs/promises";
+import path from "path";
+async function ensureEnvVariables(appPath) {
+  try {
+    const envLocalPath = path.join(appPath, ".env.local");
+    const envExamplePath = path.join(appPath, ".env.example");
+    const envLocalExists = await fs2.access(envLocalPath).then(() => true).catch(() => false);
+    const envExampleExists = await fs2.access(envExamplePath).then(() => true).catch(() => false);
+    if (!envLocalExists && !envExampleExists) {
+      return {
+        success: true,
+        created: false
+      };
+    }
+    if (!envLocalExists && envExampleExists) {
+      const envExampleContent = await fs2.readFile(envExamplePath, "utf-8");
+      await fs2.writeFile(envLocalPath, envExampleContent, "utf-8");
+      return {
+        success: true,
+        created: true
+      };
+    }
+    const envContent = await fs2.readFile(envLocalPath, "utf-8");
+    const hasGtmId = envContent.includes("NEXT_PUBLIC_GTM_ID");
+    const hasPosthogKey = envContent.includes("NEXT_PUBLIC_POSTHOG_KEY");
+    if (hasGtmId && hasPosthogKey) {
+      return {
+        success: true
+      };
+    }
+    let updatedContent = envContent;
+    if (!envContent.endsWith("\n")) {
+      updatedContent += "\n";
+    }
+    updatedContent += "\n# Analytics Configuration (added by analytics-web plugin)\n";
+    if (!hasGtmId) {
+      updatedContent += "# Get this from https://tagmanager.google.com\nNEXT_PUBLIC_GTM_ID=\n";
+    }
+    if (!hasPosthogKey) {
+      updatedContent += "# Get this from https://posthog.com (Project Settings > API Keys)\nNEXT_PUBLIC_POSTHOG_KEY=\n";
+    }
+    await fs2.writeFile(envLocalPath, updatedContent, "utf-8");
+    return {
+      success: true
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/utils/config-modifier.ts
+import fs3 from "fs/promises";
+async function addTailwindContent(filePath, contentPath) {
+  try {
+    const fileExists = await fs3.access(filePath).then(() => true).catch(() => false);
+    if (!fileExists) {
+      return {
+        success: false,
+        error: `File not found: ${filePath}`
+      };
+    }
+    const content = await fs3.readFile(filePath, "utf-8");
+    if (content.includes(contentPath)) {
+      return {
+        success: true,
+        alreadyExists: true
+      };
+    }
+    const lines = content.split("\n");
+    let contentArrayStartIndex = -1;
+    let contentArrayEndIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.includes("content:") && line.includes("[")) {
+        contentArrayStartIndex = i;
+        if (line.includes("]")) {
+          contentArrayEndIndex = i;
+          break;
+        }
+        for (let j = i + 1; j < lines.length; j++) {
+          if (lines[j].includes("]")) {
+            contentArrayEndIndex = j;
+            break;
+          }
+        }
+        break;
+      }
+    }
+    if (contentArrayStartIndex === -1) {
+      return {
+        success: false,
+        error: "Could not find content array in Tailwind config"
+      };
+    }
+    let indentation = "    ";
+    for (let i = contentArrayStartIndex + 1; i < contentArrayEndIndex; i++) {
+      const match = lines[i].match(/^(\s+)['"]/);
+      if (match) {
+        indentation = match[1];
+        break;
+      }
+    }
+    const newLine = `${indentation}'${contentPath}',`;
+    lines.splice(contentArrayEndIndex, 0, newLine);
+    const newContent = lines.join("\n");
+    await fs3.writeFile(filePath, newContent, "utf-8");
+    return {
+      success: true
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/generator.ts
+var AnalyticsWebGenerator = class extends StandardGenerator {
+  constructor(context) {
+    super(context);
+  }
+  async injectCode() {
+    console.log(chalk.cyan("\u{1F527} Configuring analytics...\n"));
+    await this.updateTailwindConfig();
+    await this.wrapLayout();
+    await this.updateEnvFile();
+  }
+  async updateTailwindConfig() {
+    const tailwindConfigPath = path2.join(this.context.appPath, "tailwind.config.ts");
+    const result1 = await addTailwindContent(tailwindConfigPath, "node_modules/@launch77-shared/lib-analytics-web/dist/**/*.js");
+    const result2 = await addTailwindContent(tailwindConfigPath, "../../node_modules/@launch77-shared/lib-analytics-web/dist/**/*.js");
+    if (result1.success || result2.success) {
+      if (result1.alreadyExists && result2.alreadyExists) {
+        console.log(chalk.gray("   \u2713 Analytics library already configured in tailwind.config.ts"));
+      } else {
+        console.log(chalk.green("   \u2713 Added Analytics library to Tailwind content paths"));
+      }
+    } else {
+      console.log(chalk.yellow(`   \u26A0\uFE0F  Could not auto-configure tailwind.config.ts: ${result1.error}`));
+      console.log(chalk.gray("   You will need to add the content paths manually:"));
+      console.log(chalk.gray("   'node_modules/@launch77-shared/lib-analytics-web/dist/**/*.js'"));
+      console.log(chalk.gray("   '../../node_modules/@launch77-shared/lib-analytics-web/dist/**/*.js'"));
+    }
+  }
+  async wrapLayout() {
+    const layoutPath = path2.join(this.context.appPath, "src/app/layout.tsx");
+    const result = await wrapWithAnalyticsProvider(layoutPath);
+    if (result.success) {
+      if (result.alreadyExists) {
+        console.log(chalk.gray("   \u2713 AnalyticsProvider already configured in layout.tsx"));
+      } else {
+        console.log(chalk.green("   \u2713 Wrapped app with AnalyticsProvider in layout.tsx"));
+      }
+    } else {
+      console.log(chalk.yellow(`   \u26A0\uFE0F  Could not auto-configure layout.tsx: ${result.error}`));
+      console.log(chalk.gray("   You will need to add AnalyticsProvider manually"));
+      console.log(chalk.gray("   See src/modules/analytics/README.md for instructions"));
+    }
+  }
+  async updateEnvFile() {
+    const result = await ensureEnvVariables(this.context.appPath);
+    if (result.success) {
+      if (result.created) {
+        console.log(chalk.green("   \u2713 Created .env.local from .env.example"));
+      } else {
+        console.log(chalk.gray("   \u2713 Environment variables template ready"));
+      }
+    } else {
+      console.log(chalk.yellow(`   \u26A0\uFE0F  Could not configure environment: ${result.error}`));
+      console.log(chalk.gray("   See .env.example for required variables"));
+    }
+  }
+  showNextSteps() {
+    console.log(chalk.bold.green("\n\u2705 Analytics Plugin Installed!\n"));
+    console.log(chalk.bold("Next Steps:\n"));
+    console.log("1. Add your analytics credentials to .env.local:");
+    console.log(chalk.cyan("   NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX"));
+    console.log(chalk.cyan("   NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxx...\n"));
+    console.log("2. Test analytics tracking:");
+    console.log(chalk.cyan("   Visit http://localhost:3000/analytics-test\n"));
+    console.log("3. Customize the consent banner:");
+    console.log(chalk.cyan("   Edit src/components/ConsentBanner.tsx\n"));
+    console.log(chalk.white("Documentation:\n"));
+    console.log(chalk.gray("See src/modules/analytics/README.md for:\n"));
+    console.log(chalk.gray("  \u2022 How to get GTM ID and PostHog key"));
+    console.log(chalk.gray("  \u2022 Usage examples and best practices"));
+    console.log(chalk.gray("  \u2022 Privacy and GDPR compliance"));
+    console.log(chalk.gray("  \u2022 Debugging and troubleshooting\n"));
+  }
+};
+async function main() {
+  const args = process.argv.slice(2);
+  const appPath = args.find((arg) => arg.startsWith("--appPath="))?.split("=")[1];
+  const appName = args.find((arg) => arg.startsWith("--appName="))?.split("=")[1];
+  const workspaceName = args.find((arg) => arg.startsWith("--workspaceName="))?.split("=")[1];
+  const pluginPath = args.find((arg) => arg.startsWith("--pluginPath="))?.split("=")[1];
+  if (!appPath || !appName || !workspaceName || !pluginPath) {
+    console.error(chalk.red("Error: Missing required arguments"));
+    console.error(chalk.gray("Usage: --appPath=<path> --appName=<name> --workspaceName=<name> --pluginPath=<path>"));
+    process.exit(1);
+  }
+  const generator = new AnalyticsWebGenerator({ appPath, appName, workspaceName, pluginPath });
+  await generator.run();
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(chalk.red("\n\u274C Error during plugin setup:"));
+    console.error(error);
+    process.exit(1);
+  });
+}
+export {
+  AnalyticsWebGenerator
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@launch77-shared/plugin-analytics-web",
+  "version": "0.0.1",
+  "description": "Launch77 plugin for analytics-web",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "dist/generator.js",
+  "bin": {
+    "generate": "./dist/generator.js"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "plugin.json"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/**/*.ts",
+    "release:connect": "launch77-release-connect",
+    "release:verify": "launch77-release-verify"
+  },
+  "dependencies": {
+    "@launch77/plugin-runtime": "^0.1.0",
+    "chalk": "^5.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "launch77": {
+    "installedPlugins": {
+      "release": {
+        "package": "release",
+        "version": "1.0.1",
+        "installedAt": "2026-01-26T01:02:24.730Z",
+        "source": "local"
+      }
+    }
+  }
+}

package/plugin.json

@@ -0,0 +1,7 @@
+{
+  "targets": ["app"],
+  "pluginDependencies": {},
+  "libraryDependencies": {
+    "@launch77-shared/lib-analytics-web": "^0.1.0"
+  }
+}

package/templates/.env.example

@@ -0,0 +1,24 @@
+# Analytics Configuration
+# Copy this file to .env.local and fill in your actual values
+
+# Google Tag Manager ID
+# Get this from: https://tagmanager.google.com
+# Format: GTM-XXXXXXX
+NEXT_PUBLIC_GTM_ID=
+
+# PostHog API Key
+# Get this from: https://posthog.com (Project Settings > API Keys)
+# Format: phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+NEXT_PUBLIC_POSTHOG_KEY=
+
+# PostHog Host (optional - defaults to https://app.posthog.com)
+# Use this if you're self-hosting PostHog
+# NEXT_PUBLIC_POSTHOG_HOST=https://your-posthog-instance.com
+
+# Analytics Configuration
+# Enable/disable analytics entirely (useful for development)
+# NEXT_PUBLIC_ANALYTICS_ENABLED=true
+
+# Development Mode
+# In development, analytics events are logged to console but may not be sent
+# to production endpoints (depends on your GTM/PostHog configuration)

package/templates/src/app/analytics-test/components/CodeExample.tsx

@@ -0,0 +1,14 @@
+interface CodeExampleProps {
+  children: string
+}
+
+/**
+ * Component for displaying formatted code examples in analytics test page
+ */
+export function CodeExample({ children }: CodeExampleProps) {
+  return (
+    <div className="mt-4 rounded bg-muted p-3">
+      <code className="text-xs whitespace-pre-wrap">{children}</code>
+    </div>
+  )
+}

package/templates/src/app/analytics-test/components/ConsentDisplay.tsx

@@ -0,0 +1,61 @@
+import type { ConsentState } from '@launch77-shared/lib-analytics-web'
+
+interface ConsentDisplayProps {
+  consent: ConsentState
+}
+
+/**
+ * Type-safe component for displaying consent state
+ * Handles all three states: undefined (loading), 'NOT_SET', and ConsentPreferences object
+ */
+export function ConsentDisplay({ consent }: ConsentDisplayProps) {
+  // Loading state
+  if (consent === undefined) {
+    return (
+      <div className="space-y-2">
+        <p>
+          <strong>Current Consent:</strong> <span className="rounded px-2 py-1 text-sm font-medium bg-gray-100 text-gray-800 dark:bg-gray-900 dark:text-gray-200">Loading...</span>
+        </p>
+        <p className="text-sm text-muted-foreground">⏳ Initializing analytics system</p>
+      </div>
+    )
+  }
+
+  // Not set state
+  if (consent === 'NOT_SET') {
+    return (
+      <div className="space-y-2">
+        <p>
+          <strong>Current Consent:</strong> <span className="rounded px-2 py-1 text-sm font-medium bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-200">Not Set</span>
+        </p>
+        <p className="text-sm text-muted-foreground">⚠ Waiting for user consent</p>
+      </div>
+    )
+  }
+
+  // ConsentPreferences object - user has made a choice
+  return (
+    <div className="space-y-3">
+      <p>
+        <strong>Current Consent:</strong> <span className="rounded px-2 py-1 text-sm font-medium bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200">Set</span>
+      </p>
+
+      <div className="space-y-2 text-sm">
+        <div className="flex items-center justify-between">
+          <span className="text-muted-foreground">Analytics Tracking:</span>
+          <span className={`rounded px-2 py-0.5 text-xs font-medium ${consent.analytics ? 'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200' : 'bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200'}`}>{consent.analytics ? '✓ Enabled' : '✗ Disabled'}</span>
+        </div>
+        <div className="flex items-center justify-between">
+          <span className="text-muted-foreground">Marketing Tracking:</span>
+          <span className={`rounded px-2 py-0.5 text-xs font-medium ${consent.marketing ? 'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200' : 'bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200'}`}>{consent.marketing ? '✓ Enabled' : '✗ Disabled'}</span>
+        </div>
+        <div className="flex items-center justify-between">
+          <span className="text-muted-foreground">Consent Given:</span>
+          <span className="text-xs text-muted-foreground">{new Date(consent.timestamp).toLocaleString()}</span>
+        </div>
+      </div>
+
+      <p className="text-sm text-muted-foreground">{consent.analytics ? '✓ Analytics is tracking events' : '✗ Analytics is disabled (user declined)'}</p>
+    </div>
+  )
+}

package/templates/src/app/analytics-test/page.tsx

@@ -0,0 +1,200 @@
+'use client'
+
+import { useAnalytics, usePageTracking, CTAButton } from '@launch77-shared/lib-analytics-web'
+import { useEffect } from 'react'
+import { ConsentDisplay } from './components/ConsentDisplay'
+import { CodeExample } from './components/CodeExample'
+
+/**
+ * Analytics Test Page
+ *
+ * This page demonstrates all analytics features and helps you verify
+ * that tracking is working correctly.
+ *
+ * Open your browser's Network tab and PostHog/GTM debug tools to see events.
+ */
+export default function AnalyticsTestPage() {
+  const { trackClick, trackForm, trackCustom, consent } = useAnalytics()
+
+  // Auto-track page views on route changes
+  usePageTracking()
+
+  useEffect(() => {
+    // Track custom event on page load
+    trackCustom({
+      action: 'page_visit',
+      category: 'test',
+      label: 'Analytics Test Page',
+      metadata: {
+        timestamp: new Date().toISOString(),
+      },
+    })
+  }, [trackCustom])
+
+  const handleManualClick = () => {
+    trackClick({
+      action: 'click_manual_button',
+      category: 'test',
+      label: 'Manual Tracking Button',
+    })
+  }
+
+  const handleFormSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    trackForm({
+      action: 'submit',
+      category: 'test',
+      label: 'Test Form',
+      formName: 'analytics_test_form',
+    })
+    alert('Form submitted! Check your analytics dashboard.')
+  }
+
+  return (
+    <div className="mx-auto max-w-4xl p-8">
+      <h1 className="mb-8 text-4xl font-bold">Analytics Test Page</h1>
+
+      {/* Consent Status */}
+      <section className="mb-8 rounded-lg border border-border bg-card p-6">
+        <h2 className="mb-4 text-2xl font-semibold">Consent Status</h2>
+        <ConsentDisplay consent={consent} />
+      </section>
+
+      {/* Manual Tracking */}
+      <section className="mb-8 rounded-lg border border-border bg-card p-6">
+        <h2 className="mb-4 text-2xl font-semibold">Manual Event Tracking</h2>
+        <p className="mb-4 text-muted-foreground">
+          Use the <code className="rounded bg-muted px-1 py-0.5">trackClick()</code> hook to manually track events.
+        </p>
+        <button onClick={handleManualClick} className="rounded-lg bg-primary px-4 py-2 text-primary-foreground hover:bg-primary/90">
+          Track Manual Click
+        </button>
+        <CodeExample>{`trackClick({
+  action: 'click_manual_button',
+  category: 'test',
+  label: 'Manual Tracking Button'
+})`}</CodeExample>
+      </section>
+
+      {/* CTAButton Component */}
+      <section className="mb-8 rounded-lg border border-border bg-card p-6">
+        <h2 className="mb-4 text-2xl font-semibold">CTAButton Component</h2>
+        <p className="mb-4 text-muted-foreground">
+          Use <code className="rounded bg-muted px-1 py-0.5">CTAButton</code> for marketing call-to-action buttons with automatic tracking.
+        </p>
+        <div className="flex gap-4">
+          <CTAButton href="/signup" trackingData={{ location: 'test_page', text: 'Get Started' }}>
+            Get Started
+          </CTAButton>
+          <CTAButton href="/demo" variant="outline" trackingData={{ location: 'test_page', text: 'Book Demo' }}>
+            Book Demo
+          </CTAButton>
+        </div>
+        <CodeExample>{`<CTAButton
+  href="/signup"
+  trackingData={{ location: "test_page", text: "Get Started" }}
+>
+  Get Started
+</CTAButton>`}</CodeExample>
+      </section>
+
+      {/* Form Tracking */}
+      <section className="mb-8 rounded-lg border border-border bg-card p-6">
+        <h2 className="mb-4 text-2xl font-semibold">Form Tracking</h2>
+        <p className="mb-4 text-muted-foreground">
+          Use <code className="rounded bg-muted px-1 py-0.5">trackForm()</code> to track form interactions.
+        </p>
+        <form onSubmit={handleFormSubmit} className="space-y-4">
+          <div>
+            <label htmlFor="name" className="mb-1 block text-sm font-medium">
+              Name
+            </label>
+            <input id="name" type="text" className="w-full rounded-md border border-input bg-background px-3 py-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring" placeholder="Enter your name" />
+          </div>
+          <div>
+            <label htmlFor="email" className="mb-1 block text-sm font-medium">
+              Email
+            </label>
+            <input id="email" type="email" className="w-full rounded-md border border-input bg-background px-3 py-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring" placeholder="Enter your email" />
+          </div>
+          <button type="submit" className="rounded-lg bg-primary px-4 py-2 text-primary-foreground hover:bg-primary/90">
+            Submit Test Form
+          </button>
+        </form>
+        <CodeExample>{`trackForm({
+  action: 'submit',
+  category: 'test',
+  label: 'Test Form',
+  formName: 'analytics_test_form'
+})`}</CodeExample>
+      </section>
+
+      {/* Custom Events */}
+      <section className="mb-8 rounded-lg border border-border bg-card p-6">
+        <h2 className="mb-4 text-2xl font-semibold">Custom Events</h2>
+        <p className="mb-4 text-muted-foreground">
+          Use <code className="rounded bg-muted px-1 py-0.5">trackCustom()</code> to track any custom event with metadata.
+        </p>
+        <button
+          onClick={() =>
+            trackCustom({
+              action: 'custom_event',
+              category: 'test',
+              label: 'Custom Event Example',
+              metadata: {
+                timestamp: new Date().toISOString(),
+                userAction: 'button_click',
+                testId: Math.random().toString(36).substring(7),
+              },
+            })
+          }
+          className="rounded-lg bg-primary px-4 py-2 text-primary-foreground hover:bg-primary/90"
+        >
+          Send Custom Event
+        </button>
+        <CodeExample>{`trackCustom({
+  action: 'custom_event',
+  category: 'test',
+  label: 'Custom Event Example',
+  metadata: {
+    timestamp: new Date().toISOString(),
+    userAction: 'button_click'
+  }
+})`}</CodeExample>
+      </section>
+
+      {/* Debug Instructions */}
+      <section className="rounded-lg border border-border bg-muted p-6">
+        <h2 className="mb-4 text-2xl font-semibold">Debugging</h2>
+        <div className="space-y-4 text-sm">
+          <div>
+            <h3 className="mb-2 font-semibold">Browser Console</h3>
+            <p className="text-muted-foreground">Open DevTools Console to see analytics events logged by the library (in development mode).</p>
+          </div>
+          <div>
+            <h3 className="mb-2 font-semibold">PostHog Debug</h3>
+            <p className="text-muted-foreground">
+              Install the PostHog toolbar:{' '}
+              <a href="https://posthog.com/docs/libraries/js#toolbar" target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">
+                https://posthog.com/docs/libraries/js#toolbar
+              </a>
+            </p>
+          </div>
+          <div>
+            <h3 className="mb-2 font-semibold">Google Tag Manager</h3>
+            <p className="text-muted-foreground">
+              Use GTM Preview mode:{' '}
+              <a href="https://tagmanager.google.com/" target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">
+                https://tagmanager.google.com/
+              </a>
+            </p>
+          </div>
+          <div>
+            <h3 className="mb-2 font-semibold">Network Tab</h3>
+            <p className="text-muted-foreground">Filter by &quot;collect&quot; or &quot;event&quot; to see tracking requests in the Network tab.</p>
+          </div>
+        </div>
+      </section>
+    </div>
+  )
+}

package/templates/src/modules/analytics/README.md

@@ -0,0 +1,550 @@
+# Launch77 Analytics
+
+Privacy-first analytics integration for web applications with GDPR-compliant consent management.
+
+## Features
+
+- 🔒 **GDPR Compliant** - Built-in consent management and PII sanitization
+- 📊 **Dual Platform** - Google Tag Manager + PostHog integration
+- 🎯 **Event Tracking** - Page views, clicks, forms, and custom events
+- 🚀 **Ready Components** - Pre-built trackable buttons and links
+- 🔐 **Privacy First** - No tracking until user consent
+- 📱 **Auto Tracking** - SPA page tracking and scroll depth
+- 🎨 **Customizable** - Full control over consent UI and tracking
+
+## Quick Start
+
+The plugin has already configured your app with:
+
+1. ✅ AnalyticsProvider wrapper in your app layout
+2. ✅ Consent banner component
+3. ✅ Environment variables template
+4. ✅ Test page with examples
+
+You're ready to configure your analytics platforms!
+
+## Configuration
+
+### 1. Set Up Environment Variables
+
+Copy `.env.example` to `.env.local` and add your credentials:
+
+```bash
+# .env.local
+NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX
+NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+#### Getting Your Credentials
+
+**Google Tag Manager:**
+
+1. Go to [https://tagmanager.google.com](https://tagmanager.google.com)
+2. Create a container (or use existing)
+3. Find your GTM ID in the format `GTM-XXXXXXX`
+
+**PostHog:**
+
+1. Go to [https://posthog.com](https://posthog.com) (or your self-hosted instance)
+2. Navigate to Project Settings > API Keys
+3. Copy your Project API Key (format: `phc_xxxxx...`)
+
+### 2. Verify Setup
+
+Visit the test page to verify analytics is working:
+
+```bash
+npm run dev
+# Navigate to http://localhost:3000/analytics-test
+```
+
+The test page shows:
+
+- Consent status
+- Manual event tracking
+- Trackable components
+- Form tracking
+- Custom events
+- Debug instructions
+
+### 3. Customize Consent Banner
+
+Edit `src/components/ConsentBanner.tsx` to match your brand:
+
+- Update text and styling
+- Link to your privacy policy
+- Adjust button design
+- Add additional consent options if needed
+
+## Usage
+
+### Basic Tracking
+
+```tsx
+'use client'
+
+import { useAnalytics } from '@launch77-shared/lib-analytics-web'
+
+function MyComponent() {
+  const { trackClick, trackPageView, trackCustom } = useAnalytics()
+
+  return (
+    <button
+      onClick={() =>
+        trackClick({
+          action: 'click_cta',
+          category: 'marketing',
+          label: 'Hero CTA',
+        })
+      }
+    >
+      Get Started
+    </button>
+  )
+}
+```
+
+### Trackable Components
+
+Use pre-built components for automatic tracking:
+
+```tsx
+import { TrackableButton, TrackableLink } from '@launch77-shared/lib-analytics-web'
+
+function HeroSection() {
+  return (
+    <>
+      <TrackableButton eventAction="click_signup" eventCategory="conversion" eventLabel="Hero Signup Button" className="bg-primary text-primary-foreground px-6 py-3 rounded-lg">
+        Sign Up Now
+      </TrackableButton>
+
+      <TrackableLink href="/pricing" eventAction="click_pricing" eventCategory="navigation" eventLabel="Hero Pricing Link" className="text-primary hover:underline">
+        View Pricing
+      </TrackableLink>
+    </>
+  )
+}
+```
+
+### Page View Tracking
+
+Auto-track SPA navigation:
+
+```tsx
+'use client'
+
+import { usePageTracking } from '@launch77-shared/lib-analytics-web'
+
+export default function Layout({ children }) {
+  // Automatically tracks page changes
+  usePageTracking()
+
+  return <>{children}</>
+}
+```
+
+### Form Tracking
+
+Track form submissions:
+
+```tsx
+'use client'
+
+import { useAnalytics } from '@launch77-shared/lib-analytics-web'
+
+function ContactForm() {
+  const { trackForm } = useAnalytics()
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+
+    // Track form submission
+    trackForm({
+      action: 'submit',
+      category: 'lead_generation',
+      label: 'Contact Form',
+      formName: 'contact_form',
+    })
+
+    // Your form submission logic...
+  }
+
+  return <form onSubmit={handleSubmit}>{/* Form fields */}</form>
+}
+```
+
+### Custom Events
+
+Track any custom event with metadata:
+
+```tsx
+import { useAnalytics } from '@launch77-shared/lib-analytics-web'
+
+function VideoPlayer() {
+  const { trackCustom } = useAnalytics()
+
+  const handlePlay = () => {
+    trackCustom({
+      action: 'video_play',
+      category: 'engagement',
+      label: 'Product Demo Video',
+      metadata: {
+        video_id: 'demo_v1',
+        duration: 120,
+        timestamp: new Date().toISOString(),
+      },
+    })
+  }
+
+  return <video onPlay={handlePlay}>...</video>
+}
+```
+
+### Scroll Tracking
+
+Track user scroll depth:
+
+```tsx
+'use client'
+
+import { useScrollTracking } from '@launch77-shared/lib-analytics-web'
+
+export default function BlogPost() {
+  // Tracks when user scrolls to 25%, 50%, 75%, 100%
+  useScrollTracking()
+
+  return <article>{/* Your content */}</article>
+}
+```
+
+## Consent Management
+
+### Checking Consent Status
+
+```tsx
+import { useAnalytics } from '@launch77-shared/lib-analytics-web'
+
+function MyComponent() {
+  const { consent, hasConsent } = useAnalytics()
+
+  if (consent === 'NOT_SET') {
+    return <p>Please accept cookies to use this feature</p>
+  }
+
+  if (!hasConsent()) {
+    return <p>Analytics is disabled</p>
+  }
+
+  // User has consented, show full features
+  return <div>...</div>
+}
+```
+
+### Programmatic Consent
+
+```tsx
+import { useAnalytics } from '@launch77-shared/lib-analytics-web'
+
+function SettingsPage() {
+  const { saveConsent, consent } = useAnalytics()
+
+  return (
+    <div>
+      <h2>Privacy Settings</h2>
+      <button onClick={() => saveConsent(true)}>Enable Analytics</button>
+      <button onClick={() => saveConsent(false)}>Disable Analytics</button>
+      <p>Current: {consent}</p>
+    </div>
+  )
+}
+```
+
+## Privacy & GDPR
+
+### How Consent Works
+
+1. **First Visit**: `consent === 'NOT_SET'` - No tracking occurs
+2. **User Accepts**: `consent === 'GRANTED'` - Full tracking enabled
+3. **User Declines**: `consent === 'DENIED'` - No tracking, saved in localStorage
+4. **Persistence**: Preference saved in `localStorage` as `analytics_consent`
+
+### PII Sanitization
+
+The library automatically sanitizes potentially sensitive data:
+
+- Email addresses
+- Phone numbers
+- Credit card numbers
+- Social security numbers
+
+### Google Consent Mode
+
+Automatically integrates with Google Consent Mode v2 for GDPR compliance.
+
+### Data Collected
+
+When consent is granted, the library tracks:
+
+- ✅ Page URLs and paths
+- ✅ Button/link clicks
+- ✅ Form submissions
+- ✅ Custom events
+- ✅ User interactions
+- ✅ Anonymous user ID (generated by PostHog/GTM)
+
+When consent is denied:
+
+- ❌ No tracking occurs
+- ❌ No analytics scripts loaded
+- ❌ No data sent to third parties
+
+## Advanced Usage
+
+### Conditional Analytics
+
+```tsx
+import { useAnalytics } from '@launch77-shared/lib-analytics-web'
+
+function FeatureButton() {
+  const { hasConsent, trackClick } = useAnalytics()
+
+  const handleClick = () => {
+    // Only track if user consented
+    if (hasConsent()) {
+      trackClick({
+        action: 'feature_click',
+        category: 'engagement',
+        label: 'Premium Feature',
+      })
+    }
+
+    // Always execute feature logic
+    performFeatureAction()
+  }
+
+  return <button onClick={handleClick}>Use Feature</button>
+}
+```
+
+### Environment-Based Config
+
+```tsx
+// Only enable analytics in production
+const isProduction = process.env.NODE_ENV === 'production'
+const analyticsEnabled = process.env.NEXT_PUBLIC_ANALYTICS_ENABLED !== 'false'
+
+<AnalyticsProvider
+  gtmId={isProduction ? process.env.NEXT_PUBLIC_GTM_ID : undefined}
+  posthogKey={analyticsEnabled ? process.env.NEXT_PUBLIC_POSTHOG_KEY : undefined}
+>
+  {children}
+</AnalyticsProvider>
+```
+
+### Self-Hosted PostHog
+
+```tsx
+<AnalyticsProvider
+  gtmId={process.env.NEXT_PUBLIC_GTM_ID}
+  posthogKey={process.env.NEXT_PUBLIC_POSTHOG_KEY}
+  posthogConfig={{
+    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://app.posthog.com',
+  }}
+>
+  {children}
+</AnalyticsProvider>
+```
+
+## Debugging
+
+### Browser Console
+
+In development mode, all events are logged to the console:
+
+```
+[Analytics] Page View: /home
+[Analytics] Click Event: { action: 'click_cta', category: 'marketing' }
+```
+
+### PostHog Toolbar
+
+Install the PostHog toolbar for real-time event debugging:
+
+1. Add `?ph_debug=true` to your URL
+2. Or enable in PostHog project settings
+3. See events as they're sent
+
+### Google Tag Manager Preview
+
+1. Go to [https://tagmanager.google.com](https://tagmanager.google.com)
+2. Click "Preview" in your container
+3. Enter your localhost URL
+4. See events in real-time
+
+### Network Tab
+
+Filter by:
+
+- `collect` - Google Analytics events
+- `event` - PostHog events
+- `gtm` - GTM script loads
+
+## Troubleshooting
+
+### Events Not Appearing
+
+**Issue:** Events aren't showing up in PostHog/GTM.
+
+**Solutions:**
+
+1. Check consent status - events only fire when `consent === 'GRANTED'`
+2. Verify environment variables are set correctly
+3. Check browser console for errors
+4. Ensure AnalyticsProvider is wrapping your app
+5. Try clearing localStorage and re-consenting
+
+### Consent Banner Not Showing
+
+**Issue:** ConsentBanner component doesn't appear.
+
+**Solutions:**
+
+1. Import and render `<ConsentBanner />` in your root layout
+2. Check if consent is already set in localStorage (clear to test)
+3. Verify component is in a Client Component (`'use client'`)
+
+### TypeScript Errors
+
+**Issue:** Type errors with analytics functions.
+
+**Solutions:**
+
+1. Ensure `@launch77-shared/lib-analytics-web` is installed
+2. Restart TypeScript server in VS Code
+3. Check that types are exported from library
+
+### Build Failures
+
+**Issue:** Build fails with module not found.
+
+**Solutions:**
+
+1. Run `npm install` at workspace root
+2. Verify library is in package.json dependencies
+3. Check that paths are correct in imports
+4. Restart dev server
+
+## Best Practices
+
+### Do's ✅
+
+- Always check consent before showing analytics-dependent features
+- Use trackable components for consistent tracking
+- Add meaningful labels and categories to events
+- Test analytics in production-like environment
+- Document custom events for your team
+- Use TypeScript for type safety
+
+### Don'ts ❌
+
+- Don't track without consent
+- Don't include PII in event metadata
+- Don't track sensitive user actions
+- Don't hardcode analytics IDs in code
+- Don't skip testing consent flow
+- Don't forget to update privacy policy
+
+## Event Naming Conventions
+
+Follow consistent naming for better analytics:
+
+```tsx
+// ✅ Good - Clear action, category, label
+trackClick({
+  action: 'click_signup_button',
+  category: 'conversion',
+  label: 'Header Signup CTA',
+})
+
+// ❌ Bad - Vague, inconsistent
+trackClick({
+  action: 'clicked',
+  category: 'button',
+  label: 'Signup',
+})
+```
+
+### Recommended Structure
+
+- **Action**: `verb_noun_context` (e.g., `click_button_submit`, `view_page_pricing`)
+- **Category**: Business domain (e.g., `conversion`, `engagement`, `navigation`)
+- **Label**: Specific identifier (e.g., `Hero CTA`, `Footer Link`, `Mobile Menu`)
+
+## Integration with Other Tools
+
+### Google Analytics 4
+
+Configure GA4 tags in GTM to receive events from the analytics library.
+
+### Segment
+
+You can wrap this library's events and forward to Segment if needed.
+
+### Mixpanel
+
+PostHog can export data to Mixpanel via integrations.
+
+### Custom Analytics
+
+Use `trackCustom()` to send events to any analytics platform:
+
+```tsx
+const { trackCustom } = useAnalytics()
+
+trackCustom({
+  action: 'my_event',
+  category: 'custom',
+  label: 'My Label',
+  metadata: {
+    // Your custom metadata
+  },
+})
+```
+
+## Performance
+
+### Bundle Size
+
+The analytics library is tree-shakeable and only includes:
+
+- PostHog JS (~60KB gzipped)
+- GTM via @next/third-parties (optimized loading)
+
+### Loading Strategy
+
+- GTM script loads asynchronously
+- PostHog initializes after consent
+- No blocking of page render
+- Minimal performance impact
+
+## Next Steps
+
+1. **Configure Platforms** - Add GTM and PostHog credentials to `.env.local`
+2. **Test Tracking** - Visit `/analytics-test` and verify events
+3. **Customize Consent Banner** - Update `ConsentBanner.tsx` with your brand
+4. **Add Tracking** - Use hooks and components throughout your app
+5. **Set Up Dashboards** - Create PostHog/GTM dashboards for your events
+6. **Update Privacy Policy** - Document analytics usage in privacy policy
+7. **Train Team** - Share event naming conventions with developers
+
+## Resources
+
+- **Library Documentation**: `node_modules/@launch77-shared/lib-analytics-web/README.md`
+- **PostHog Docs**: [https://posthog.com/docs](https://posthog.com/docs)
+- **GTM Docs**: [https://developers.google.com/tag-manager](https://developers.google.com/tag-manager)
+- **Google Consent Mode**: [https://support.google.com/tagmanager/answer/10718549](https://support.google.com/tagmanager/answer/10718549)
+- **GDPR Compliance**: [https://gdpr.eu](https://gdpr.eu)
+
+---
+
+Need help? Check the analytics library README or ask in the Launch77 community.