@stacksjs/analytics 0.75.15 → 0.75.16

package/README.md

@@ -12,16 +12,39 @@ This package integrates analytics features into your application.
 bun install -d @stacksjs/analytics
 ```
 
-You may now use:
+Render the driver selected in `config/analytics.ts`:
 
 ```ts
-import { analytics } from '@stacksjs/analytics'
+import { generateAnalyticsScript } from '@stacksjs/analytics'
+import { analytics } from '@stacksjs/config'
 
-// analytics.track('event', {
-//   property: 'value'
-// })
+const head = generateAnalyticsScript(analytics)
 ```
 
+AnalyticsHQ is the default driver. It emits no tags until
+`drivers.analyticshq.siteId` is set, so a new application never sends a broken
+or unidentified event. Name another driver explicitly to use it instead.
+
+Remote analytics can be limited to explicit application environments:
+
+```ts
+import type { AnalyticsConfig } from '@stacksjs/types'
+
+export default {
+  driver: 'analyticshq',
+  environments: ['production', 'staging'],
+  drivers: {
+    analyticshq: { siteId: 'YOUR_APP_ID' },
+  },
+} satisfies AnalyticsConfig
+```
+
+Stacks resolves `APP_ENV` before selecting or initializing the driver. An
+excluded environment emits no tracking tag. `enabled: false` always wins, an
+empty allowlist disables every environment, and local environments can opt in
+by naming their exact label. Leaving `environments` unset preserves existing
+application behavior.
+
 Learn more in the docs.
 
 ## 🧪 Testing

package/dist/registry.d.ts

@@ -7,9 +7,9 @@ export declare function isAnalyticsDriver(value: unknown): value is AnalyticsDri
 /**
  * Resolve the configured driver's head tags.
  *
- * Returns an empty array when no driver is configured at all. Throws when a
- * driver is named that Stacks does not implement, or when the named driver is
- * missing the config it needs.
+ * Defaults to AnalyticsHQ when no driver is named. Returns an empty array while
+ * that default has no site id. Throws when a driver is unknown, or when an
+ * explicitly selected third-party driver is missing the config it needs.
  */
 export declare function getAnalyticsHead(config: AnalyticsConfig): AnalyticsHeadTag[];
 /**

package/dist/registry.js

@@ -1 +1 @@
-import{integrationGate}from"@stacksjs/env";import{getAnalyticsHqHead}from"./drivers/analyticshq";import{getFathomAnalyticsHead}from"./drivers/fathom";import{getGoogleAnalyticsHead}from"./drivers/google-analytics";import{getPlausibleAnalyticsHead}from"./drivers/plausible";import{getSelfHostedAnalyticsHead}from"./drivers/self-hosted";import{renderHeadTags}from"./drivers/shared";export const ANALYTICS_DRIVERS=["google-analytics","fathom","plausible","self-hosted","analyticshq"];export function isAnalyticsDriver(value){return typeof value==="string"&&ANALYTICS_DRIVERS.includes(value)}function misconfigured(driver,key,field){return Error(`Analytics driver "${driver}" is selected but not configured: set \`drivers.${key}.${field}\` in config/analytics.ts, or change \`driver\`.`)}export function getAnalyticsHead(config){const driver=config.driver;if(!driver)return[];if(config.enabled===!1)return[];if(config.environments!==void 0&&!integrationGate(config).enabled)return[];if(!isAnalyticsDriver(driver))throw Error(`Unknown analytics driver "${String(driver)}". Available drivers: ${ANALYTICS_DRIVERS.join(", ")}.`);switch(driver){case"google-analytics":{const options=config.drivers?.googleAnalytics;if(!options?.trackingId)throw misconfigured(driver,"googleAnalytics","trackingId");return getGoogleAnalyticsHead(options)}case"fathom":{const options=config.drivers?.fathom;if(!options?.siteId)throw misconfigured(driver,"fathom","siteId");return getFathomAnalyticsHead(options)}case"plausible":{const options=config.drivers?.plausible;if(!options?.domain)throw misconfigured(driver,"plausible","domain");return getPlausibleAnalyticsHead(options)}case"self-hosted":{const options=config.drivers?.selfHosted;if(!options?.siteId)throw misconfigured(driver,"selfHosted","siteId");if(!options.apiEndpoint)throw misconfigured(driver,"selfHosted","apiEndpoint");return getSelfHostedAnalyticsHead(options)}case"analyticshq":{const options=config.drivers?.analyticshq;if(!options?.siteId)throw misconfigured(driver,"analyticshq","siteId");return getAnalyticsHqHead(options)}default:throw Error(`Analytics driver "${String(driver)}" has no implementation.`)}}export function generateAnalyticsScript(config){const tags=getAnalyticsHead(config);if(!tags.length)return"";return renderHeadTags(tags)}
+import{initializeIntegration}from"@stacksjs/env";import{getAnalyticsHqHead}from"./drivers/analyticshq";import{getFathomAnalyticsHead}from"./drivers/fathom";import{getGoogleAnalyticsHead}from"./drivers/google-analytics";import{getPlausibleAnalyticsHead}from"./drivers/plausible";import{getSelfHostedAnalyticsHead}from"./drivers/self-hosted";import{renderHeadTags}from"./drivers/shared";export const ANALYTICS_DRIVERS=["google-analytics","fathom","plausible","self-hosted","analyticshq"];export function isAnalyticsDriver(value){return typeof value==="string"&&ANALYTICS_DRIVERS.includes(value)}function misconfigured(driver,key,field){return Error(`Analytics driver "${driver}" is selected but not configured: set \`drivers.${key}.${field}\` in config/analytics.ts, or change \`driver\`.`)}export function getAnalyticsHead(config){const driver=config.driver??"analyticshq";if(config.enabled===!1)return[];if(config.environments!==void 0){const result=initializeIntegration(config,()=>resolveAnalyticsHead(config,driver));return result.initialized?result.value:[]}return resolveAnalyticsHead(config,driver)}function resolveAnalyticsHead(config,driver){if(!isAnalyticsDriver(driver))throw Error(`Unknown analytics driver "${String(driver)}". Available drivers: ${ANALYTICS_DRIVERS.join(", ")}.`);switch(driver){case"google-analytics":{const options=config.drivers?.googleAnalytics;if(!options?.trackingId)throw misconfigured(driver,"googleAnalytics","trackingId");return getGoogleAnalyticsHead(options)}case"fathom":{const options=config.drivers?.fathom;if(!options?.siteId)throw misconfigured(driver,"fathom","siteId");return getFathomAnalyticsHead(options)}case"plausible":{const options=config.drivers?.plausible;if(!options?.domain)throw misconfigured(driver,"plausible","domain");return getPlausibleAnalyticsHead(options)}case"self-hosted":{const options=config.drivers?.selfHosted;if(!options?.siteId)throw misconfigured(driver,"selfHosted","siteId");if(!options.apiEndpoint)throw misconfigured(driver,"selfHosted","apiEndpoint");return getSelfHostedAnalyticsHead(options)}case"analyticshq":{const options=config.drivers?.analyticshq;if(!options?.siteId)return[];return getAnalyticsHqHead(options)}default:throw Error(`Analytics driver "${String(driver)}" has no implementation.`)}}export function generateAnalyticsScript(config){const tags=getAnalyticsHead(config);if(!tags.length)return"";return renderHeadTags(tags)}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/analytics",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.15",
+  "version": "0.75.16",
   "description": "Stacks Analytics. Privacy-friendly.",
   "author": "Chris Breuer",
   "contributors": [
@@ -51,9 +51,9 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/database": "0.75.15",
-    "@stacksjs/env": "0.75.15",
-    "@stacksjs/types": "0.75.15"
+    "@stacksjs/database": "0.75.16",
+    "@stacksjs/env": "0.75.16",
+    "@stacksjs/types": "0.75.16"
   },
   "devDependencies": {
     "better-dx": "^0.2.24"