Update Nuxt integration documentation for Simple Analytics

Author: adriaandotcom

_docs/31_integrations/00_nuxt.md

@@ -1,83 +1,127 @@
 ---
-title: Install Simple Analytics with Nuxt 3
+title: Install Simple Analytics with Nuxt
 hidden: true
 category: integrations
 permalink: /install-simple-analytics-with-nuxt
-last_modified_at: 2023-03-03
+last_modified_at: 2025-10-24
 ---
 
-We have a package that works with both Nuxt 2 and Nuxt 3.
+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.
 
-## Nuxt 3
+## Installation
 
-Run this command to install Simple Analytics for Vue:
+```bash
+npm i @simpleanalytics/nuxt
+```
+
+## Environment Variables
+
+Set your website domain (as added in your [Simple Analytics dashboard](https://dashboard.simpleanalytics.com/)):
 
 ```bash
-npm install simple-analytics-vue --save-dev
+SIMPLE_ANALYTICS_HOSTNAME=example.com
 ```
 
-Create a file called `plugins/simpleanalytics.client.js`:
+> Omit `www.`, just the root domain or if you use a subdomain, include that. Like `sub.example.com`.
+
+## Configuration
 
-```js
-import SimpleAnalytics from "simple-analytics-vue";
+Add the module to your `nuxt.config.ts` and optionally set your hostname:
 
-export default defineNuxtPlugin((nuxtApp) => {
-  nuxtApp.vueApp.use(SimpleAnalytics);
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  // ...
+  modules: ["@simpleanalytics/nuxt"],
+  simpleAnalytics: {
+    // hostname: "example.com", // optional, if you don't use SIMPLE_ANALYTICS_HOSTNAME
+  },
 });
 ```
 
-That's it! Continue only if you want to go advanced.
+## Usage
 
-If you want to skip your own visits on development:
+### Client-side analytics
 
-```js
-import SimpleAnalytics from "simple-analytics-vue";
+The module uses the `simple-analytics-vue` plugin to auto-inject the Simple Analytics script.
 
-export default defineNuxtPlugin((nuxtApp) => {
-  nuxtApp.vueApp.use(SimpleAnalytics, {
-    skip: process.env.NODE_ENV !== "production",
-  });
-});
+### Tracking events in client components
+
+To track events programmatically, inject the `saEvent` function.
+
+```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>
 ```
 
-If you have a [custom domain for bypassing ad-blockers](/bypass-ad-blockers) set up, use this:
+### Server-side tracking (SSR & API)
 
-```js
-import SimpleAnalytics from "simple-analytics-vue";
+Track page views or events during server side rendering or in API routes:
 
-export default defineNuxtPlugin((nuxtApp) => {
-  nuxtApp.vueApp.use(SimpleAnalytics, {
-    skip: process.env.NODE_ENV !== "production",
-    domain: "api.example.com"
+#### In server-rendered pages
+
+```vue
+<script setup lang="ts">
+if (import.meta.server) {
+  await trackPageview({
+    metadata: {
+      source: "some extra context",
+    },
   });
-});
+}
+</script>
 ```
 
-## Nuxt 2
-
-Run this command to install Simple Analytics for Vue:
+#### In Nitro API routes
+
+```ts
+// server/api/signup.post.ts
+export default defineEventHandler(async (event) => {
+  await trackEvent("user_signup", {
+    event,
+    metadata: {
+      source: "registration_form",
+      user_type: "new",
+    },
+  });
 
-```bash
-npm install [email protected] --save-dev
+  // ...
+});
 ```
 
-Create a file in your plugin folder with the name `simple-analytics.js`:
+## API Reference
 
-```js
-// ~/plugins/simple-analytics.js
+### `trackPageview(options)`
 
-import SimpleAnalytics from "simple-analytics-vue";
-import Vue from "vue";
+Track a pageview on the server.
 
-Vue.use(SimpleAnalytics, { skip: process.env.NODE_ENV !== "production" });
-```
+**Parameters:**
 
-Then on your `nuxt.config.js`, make sure to include the plugin with `ssr: false` as we only want to run it on the client:
+- `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
 
-```js
-// nuxt.config.js
+### `trackEvent(eventName, options)`
 
-export default {
-  plugins: [{ src: "~/plugins/simple-analytics.js", ssr: false }],
-};
-```
+Track a custom event on the server.
+
+**Parameters:**
+
+- `eventName` (string): Name of the event to track
+- `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
+  - `collectDnt` (boolean): Whether to collect data when DNT is enabled