stacks-analytics

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:

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

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

{
  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