feat: add script settings support

Author: JeanMeijer

examples/nuxt-v3/middleware/tracking-middleware.ts

@@ -4,9 +4,5 @@ export default defineNuxtRouteMiddleware(async (to) => {
     return;
   }
 
-  if (to.path.startsWith("/api/")) {
-    return;
-  }
-
   await trackPageview();
 });

examples/nuxt-v4/app/middleware/tracking-middleware.ts

@@ -4,9 +4,5 @@ export default defineNuxtRouteMiddleware(async (to) => {
     return;
   }
 
-  if (to.path.startsWith("/api/")) {
-    return;
-  }
-
   await trackPageview();
 });

package.json

@@ -11,8 +11,7 @@
     "format": "prettier --write \"**/*.{ts,tsx,md}\""
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.5",
-    "turbo": "^2.5.5"
+    "turbo": "^2.5.6"
   },
   "packageManager": "[email protected]"
 }

packages/nuxt/README.md

@@ -1,81 +1,54 @@
-# Simple Analytics for Nuxt
+# Simple Analytics Nuxt Module
 
-This Nuxt module provides a simple way to add privacy-friendly pageview and event tracking using Simple Analytics to your Nuxt 3 or 4 application.
+A Nuxt module for integrating Simple Analytics with server-side tracking capabilities.
 
-## Installation
+## Quick Setup
+
+Install the module to your Nuxt application:
 
 ```bash
-npm i @simpleanalytics/nuxt
+npm install @simpleanalytics/nuxt
 ```
 
-## Environment Variables
-
-Set your website domain (as added in your [Simple Analytics dashboard](https://dashboard.simpleanalytics.com/)):
-
-```txt
-SIMPLE_ANALYTICS_HOSTNAME=example.com
-```
-
-## Configuration
-
-Add the module to your `nuxt.config.ts` and optionally set your hostname:
+Add the module to your `nuxt.config.ts`:
 
 ```ts
-// nuxt.config.ts
 export default defineNuxtConfig({
-  // ...
   modules: ["@simpleanalytics/nuxt"],
   simpleAnalytics: {
-    hostname: "example.com", // optional, if you don't use SIMPLE_ANALYTICS_HOSTNAME
+    hostname: "your-domain.com",
+    enabled: true,
+    proxy: true,
   },
 });
 ```
 
 ## Usage
 
-### Client-side analytics
-
-The module uses the `simple-analytics-vue` plugin to auto-inject the Simple Analytics script.
+### Server-side Pageview Tracking
 
-### Tracking events in client components
-
-To track events programmatically, inject the `saEvent` function.
+Track pageviews automatically on the server:
 
 ```vue
 <script setup>
-import { inject } from "vue";
-
-const saEvent = inject("saEvent");
-
-// e.g.: send event when liking a comment
-const likeComment = (comment) => {
-  saEvent(`comment_like_${comment.id}`);
-};
-</script>
-```
-
-### Server-side tracking (SSR & API)
-
-Track page views or events during server side rendering or in API routes:
-
-#### In server-rendered pages
-
-```vue
-<script setup lang="ts">
+// This will run on the server and track the pageview
 if (import.meta.server) {
   await trackPageview({
+    hostname: "your-domain.com",
     metadata: {
-      source: "some extra context",
+      source: "homepage",
     },
   });
 }
 </script>
 ```
 
-#### In Nitro API routes
+### Server-side Event Tracking
+
+Track custom events from API routes or server-side code:
 
 ```ts
-// server/api/signup.post.ts
+// In a server API route
 export default defineEventHandler(async (event) => {
   await trackEvent("user_signup", {
     event,
@@ -85,24 +58,80 @@ export default defineEventHandler(async (event) => {
     },
   });
 
-  // ...
+  return { success: true };
+});
+```
+
+## Configuration
+
+### Module Options
+
+```ts
+export default defineNuxtConfig({
+  simpleAnalytics: {
+    // Your Simple Analytics hostname
+    hostname: "your-domain.com",
+
+    // Enable/disable the module
+    enabled: true,
+
+    // Enable/disable proxy
+    proxy: true,
+
+    // Auto-collect events
+    autoCollect: true,
+
+    // Collect data even when DNT is enabled
+    collectDnt: false,
+
+    // Dashboard mode
+    mode: "dash",
+
+    // Ignore specific metrics
+    ignoreMetrics: {
+      referrer: false,
+      utm: false,
+      country: false,
+      session: false,
+      timeonpage: false,
+      scrolled: false,
+      useragent: false,
+      screensize: false,
+      viewportsize: false,
+      language: false,
+    },
+
+    // Ignore specific pages
+    ignorePages: ["/admin", "/private"],
+
+    // Allow specific URL parameters
+    allowParams: ["ref", "source"],
+
+    // Non-unique parameters
+    nonUniqueParams: ["utm_source"],
+
+    // Strict UTM parameter parsing
+    strictUtm: true,
+  },
 });
 ```
 
-## API Reference
+### Environment Variables
+
+```bash
+# Required: Your Simple Analytics hostname
+SIMPLE_ANALYTICS_HOSTNAME=your-domain.com
+```
+
+## API Reference (Nuxt)
 
 ### `trackPageview(options)`
 
 Track a pageview on the server.
 
 **Parameters:**
 
-- `options` (object):
-  - `hostname` (string): Your Simple Analytics hostname
-  - `metadata` (object): Additional metadata to track
-  - `ignoreMetrics` (object): Metrics to ignore for this pageview
-  - `collectDnt` (boolean): Whether to collect data when DNT is enabled
-  - `strictUtm` (boolean): Whether to use strict UTM parameter parsing
+- `options` (object): Additional metadata to track (optional)
 
 ### `trackEvent(eventName, options)`
 
@@ -111,9 +140,41 @@ Track a custom event on the server.
 **Parameters:**
 
 - `eventName` (string): Name of the event to track
+- `options` (object): Additional metadata to track (option)
+
+## API Reference (Nitro)
+
+### `trackPageview(requestEvent, options)`
+
+Track a pageview on the server.
+
+**Parameters:**
+
+- `options` (object): Additional metadata to track (optional)
+
+### `trackEvent(requestEvent, eventName, options)`
+
+Track a custom event on the server.
+
+**Parameters:**
+
 - `options` (object):
-  - `headers` (Headers): Request headers
   - `hostname` (string): Your Simple Analytics hostname
   - `metadata` (object): Additional metadata to track
-  - `ignoreMetrics` (object): Metrics to ignore for this event
+  - `ignoreMetrics` (object): Metrics to ignore for this pageview
   - `collectDnt` (boolean): Whether to collect data when DNT is enabled
+  - `strictUtm` (boolean): Whether to use strict UTM parameter parsing
+
+## Migration to v2.0
+
+## Do Not Track (DNT)
+
+### Client-side analytics
+
+### Server-side analytics
+
+## Ignoring metrics To also record DNT visitors you can add data-collect-dnt="true" to the script tag
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.

packages/nuxt/package.json

@@ -37,20 +37,21 @@
   },
   "dependencies": {
     "@nuxt/kit": "^4.0.3",
-    "simple-analytics-vue": "^3.0.3"
+    "simple-analytics-vue": "^3.1.0"
   },
   "devDependencies": {
-    "@nuxt/devtools": "^2.6.2",
-    "@nuxt/eslint-config": "^1.8.0",
+    "@nuxt/devtools": "^2.6.3",
+    "@nuxt/eslint-config": "^1.9.0",
     "@nuxt/module-builder": "^1.0.2",
     "@nuxt/schema": "^4.0.3",
     "@nuxt/test-utils": "^3.19.2",
-    "@types/node": "^24.2.1",
+    "@types/node": "^24.3.0",
     "changelogen": "^0.6.2",
-    "eslint": "^9.33.0",
+    "eslint": "^9.34.0",
     "nuxt": "^4",
     "typescript": "~5.9.2",
     "vitest": "^3.2.4",
-    "vue-tsc": "^3.0.5"
+    "vue-tsc": "^3.0.5",
+    "vue": "^3"
   }
 }

packages/nuxt/src/module.ts

@@ -6,7 +6,7 @@ import {
   addServerImports,
   addPlugin,
 } from "@nuxt/kit";
-import type { SimpleAnalyticsOptions } from "./runtime/server/lib/options";
+import type { SimpleAnalyticsOptions } from "./runtime/interfaces";
 
 export interface ModuleOptions extends SimpleAnalyticsOptions {
   enabled?: boolean;
@@ -39,23 +39,25 @@ export default defineNuxtModule<ModuleOptions>({
 
     addPlugin(resolver.resolve("./runtime/plugin"));
 
+    // Server rendering imports
     addImports([
       {
         name: "trackEvent",
-        from: resolver.resolve("./runtime/track-event"),
+        from: resolver.resolve("./runtime/server/track-event"),
         meta: {
           description: "Track a custom event with Simple Analytics",
         },
       },
       {
         name: "trackPageview",
-        from: resolver.resolve("./runtime/track-pageview"),
+        from: resolver.resolve("./runtime/server/track-pageview"),
         meta: {
           description: "Track a pageview with Simple Analytics",
         },
       },
     ]);
 
+    // Nitro imports
     addServerImports([
       {
         name: "trackEvent",

packages/nuxt/src/runtime/interfaces.ts

@@ -1,3 +1,27 @@
 export type AnalyticsMetadata =
   | Record<string, string | boolean | number | Date>
   | undefined;
+
+export interface SimpleAnalyticsOptions {
+  autoCollect?: boolean;
+  collectDnt?: boolean;
+  domain?: string;
+  hostname?: string;
+  mode?: "dash";
+  ignoreMetrics?: {
+    referrer?: boolean;
+    utm?: boolean;
+    country?: boolean;
+    session?: boolean;
+    timeonpage?: boolean;
+    scrolled?: boolean;
+    useragent?: boolean;
+    screensize?: boolean;
+    viewportsize?: boolean;
+    language?: boolean;
+  };
+  ignorePages?: string[];
+  allowParams?: string[];
+  nonUniqueParams?: string[];
+  strictUtm?: boolean;
+}

packages/nuxt/src/runtime/nitro/interface.ts

@@ -0,0 +1,5 @@
+import type { H3Event } from "h3";
+
+export interface NitroContext {
+  event: H3Event;
+} 

packages/nuxt/src/runtime/nitro/track-event.ts

@@ -5,12 +5,8 @@ import {
   isEnhancedBotDetectionEnabled,
 } from "../server/lib/utils";
 import { parseHeaders } from "../server/lib/headers";
-import type { H3Event } from "h3";
 import { useRuntimeConfig } from "#imports";
-
-type NitroContext = {
-  event: H3Event;
-};
+import type { NitroContext } from "./interface";
 
 type TrackEventOptions = TrackingOptions & NitroContext;
 
@@ -30,11 +26,7 @@ export async function trackEvent(
     return;
   }
 
-  const headers = options.event.headers;
-
-  if (!headers) {
-    return;
-  }
+  const { headers } = options.event;
 
   if (isDoNotTrackEnabled(headers) && !options?.collectDnt) {
     return;