@stacksjs/defaults 0.70.206 → 0.70.208

package/ai/skills/stacks-analytics/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: stacks-analytics
+description: Use when adding analytics to a Stacks application — configuring Fathom or self-hosted analytics, generating tracking scripts, privacy-friendly analytics setup, or the analytics configuration. Covers @stacksjs/analytics and config/analytics.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Analytics
+
+Privacy-friendly analytics with Fathom and self-hosted driver support.
+
+## Key Paths
+- Core package: `storage/framework/core/analytics/src/`
+- Configuration: `config/analytics.ts`
+
+## Drivers
+
+### Fathom Analytics
+Privacy-focused, GDPR-compliant analytics. Requires a Fathom account.
+
+### Self-Hosted Analytics
+Generate tracking scripts for self-hosted analytics:
+
+```typescript
+import { generateSelfHostedScript, getSelfHostedAnalyticsHead, generateInlineScript } from '@stacksjs/analytics'
+
+// Generate tracking script tag
+const script = generateSelfHostedScript({
+  siteId: 'ABCDEF',
+  apiEndpoint: 'https://analytics.myapp.com/api/event',
+  honorDnt: true,                // respect Do Not Track
+  trackHashChanges: false,       // track hash URL changes
+  trackOutboundLinks: true       // track external link clicks
+})
+
+// Generate head configuration for STX
+const headConfig = getSelfHostedAnalyticsHead({
+  siteId: 'ABCDEF',
+  apiEndpoint: 'https://analytics.myapp.com/api/event'
+})
+
+// Generate inline script (no external JS file)
+const inline = generateInlineScript(config)
+```
+
+## SelfHostedConfig Interface
+
+```typescript
+interface SelfHostedConfig {
+  siteId: string                  // unique site identifier
+  apiEndpoint: string             // analytics API URL
+  honorDnt?: boolean              // respect Do Not Track header
+  trackHashChanges?: boolean      // track SPA hash navigation
+  trackOutboundLinks?: boolean    // track clicks to external sites
+}
+```
+
+## config/analytics.ts
+
+```typescript
+{
+  driver: 'fathom',              // 'fathom' | 'google-analytics'
+  drivers: {
+    googleAnalytics: {
+      trackingId: ''              // GA tracking ID
+    },
+    fathom: {
+      siteId: ''                  // Fathom site ID
+    }
+  }
+}
+```
+
+## Dashboard Integration
+
+Analytics dashboard at `/dashboard/analytics` displays:
+- Page views and visitor counts
+- Traffic sources
+- Popular pages
+- Engagement metrics
+
+## Gotchas
+- Default driver is `fathom` — privacy-focused by default
+- Self-hosted analytics require your own analytics endpoint
+- `honorDnt: true` respects browser Do Not Track settings
+- `escapeAttr()` is used internally to prevent XSS in generated scripts
+- Google Analytics tracking ID goes in config, not env (unless you override)
+- Analytics scripts are generated server-side and injected into page head
+- Fathom is a paid service — self-hosted is free but requires infrastructure
+- `trackOutboundLinks` adds click handlers to external `<a>` tags