Skip to content

πŸ“ˆ Open source, privacy-first web analytics β€” a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

Add Vue / Nuxt integrations

Blue Mouse1542f17f797f
diff --git a/docs/docs/integrations/nuxt.md b/docs/docs/integrations/nuxt.md
new file mode 100644
index 000000000..e886cb9f1
--- /dev/null
+++ b/docs/docs/integrations/nuxt.md
@@ -0,0 +1,255 @@
+---
+title: Nuxt
+slug: /nuxt-integration
+---
+
+Integrate Swetrix with your [Nuxt](https://nuxt.com/) application to track page views, monitor errors, and capture custom events β€” all while staying privacy-friendly and GDPR-compliant.
+
+This guide covers **Nuxt 3**. For plain Vue apps without Nuxt, see the [Vue integration](/vue-integration) instead.
+
+## Installation
+
+Install the Swetrix npm package:
+
+```bash
+npm install swetrix
+```
+
+### Create a Swetrix plugin
+
+Nuxt plugins run once when your app initialises, making them the ideal place to set up analytics. Create `plugins/swetrix.client.ts` (the `.client` suffix ensures it only runs in the browser):
+
+```ts
+import * as Swetrix from 'swetrix'
+
+export default defineNuxtPlugin(() => {
+ const router = useRouter()
+
+ Swetrix.init('YOUR_PROJECT_ID')
+ Swetrix.trackViews()
+
+ router.afterEach(() => {
+ Swetrix.trackViews()
+ })
+})
+```
+
+That's it β€” Nuxt auto-registers files in the `plugins/` directory. Page views are now tracked on every route change.
+
+:::caution
+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.
+:::
+
+### Noscript fallback (optional)
+
+To track visitors who have JavaScript disabled, add a noscript image pixel to your `app.vue` (or `app.html` if you have a custom HTML template):
+
+```vue
+<template>
+ <div>
+ <NuxtPage />
+
+ <noscript>
+ <img
+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"
+ alt=""
+ referrerpolicy="no-referrer-when-downgrade"
+ />
+ </noscript>
+ </div>
+</template>
+```
+
+## Disable tracking in development
+
+By default, Swetrix ignores `localhost` traffic. If you want to be explicit about it, you can conditionally disable tracking based on your environment.
+
+Update `plugins/swetrix.client.ts`:
+
+```ts
+import * as Swetrix from 'swetrix'
+
+export default defineNuxtPlugin(() => {
+ const router = useRouter()
+ const config = useRuntimeConfig()
+
+ Swetrix.init(config.public.swetrixPid, {
+ disabled: process.dev,
+ })
+ Swetrix.trackViews()
+
+ router.afterEach(() => {
+ Swetrix.trackViews()
+ })
+})
+```
+
+:::tip
+If you want to verify tracking locally during development, set `devMode: true` instead:
+
+```ts
+Swetrix.init('YOUR_PROJECT_ID', {
+ devMode: true,
+})
+```
+
+Remember to remove this before deploying to production.
+:::
+
+## Check your installation
+
+Deploy your application (or temporarily enable `devMode`) and visit a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.
+
+## Error tracking
+
+Enable automatic client-side error monitoring by adding `trackErrors()` to your plugin. This captures unhandled JavaScript errors and reports them to Swetrix.
+
+Update `plugins/swetrix.client.ts`:
+
+```ts
+import * as Swetrix from 'swetrix'
+
+export default defineNuxtPlugin(() => {
+ const router = useRouter()
+
+ Swetrix.init('YOUR_PROJECT_ID')
+ Swetrix.trackViews()
+ Swetrix.trackErrors()
+
+ router.afterEach(() => {
+ Swetrix.trackViews()
+ })
+})
+```
+
+Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.
+
+## Tracking custom events
+
+Custom events let you track specific user interactions β€” button clicks, form submissions, sign-ups, purchases, and more. Import `swetrix` in any component and call `track()`.
+
+### Example: tracking button clicks
+
+```vue
+<script setup lang="ts">
+import * as Swetrix from 'swetrix'
+
+function handleClick() {
+ Swetrix.track({
+ ev: 'SIGNUP_CTA_CLICK',
+ meta: {
+ location: 'navbar',
+ },
+ })
+}
+</script>
+
+<template>
+ <button @click="handleClick">Sign up</button>
+</template>
+```
+
+### Example: tracking form submissions
+
+```vue
+<script setup lang="ts">
+import * as Swetrix from 'swetrix'
+
+function handleSubmit() {
+ Swetrix.track({
+ ev: 'CONTACT_FORM_SUBMITTED',
+ meta: {
+ source: 'support_page',
+ },
+ })
+
+ // ...submit logic
+}
+</script>
+
+<template>
+ <form @submit.prevent="handleSubmit">
+ <input type="email" placeholder="[email protected]" required />
+ <textarea placeholder="How can we help?" required />
+ <button type="submit">Send</button>
+ </form>
+</template>
+```
+
+### Example: tracking outbound links
+
+Create a reusable component for external links. Save as `components/TrackedLink.vue`:
+
+```vue
+<script setup lang="ts">
+import * as Swetrix from 'swetrix'
+
+const props = withDefaults(
+ defineProps<{
+ href: string
+ eventName?: string
+ }>(),
+ {
+ eventName: 'OUTBOUND_CLICK',
+ },
+)
+
+function handleClick() {
+ Swetrix.track({
+ ev: props.eventName,
+ meta: { url: props.href },
+ })
+}
+</script>
+
+<template>
+ <a :href="href" target="_blank" rel="noopener noreferrer" @click="handleClick">
+ <slot />
+ </a>
+</template>
+```
+
+### Event naming rules
+
+Event names must:
+
+- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)
+- Be fewer than 64 characters
+- Start with an English letter
+
+We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `SIGNUP_CTA_CLICK`, `CONTACT_FORM_SUBMITTED`).
+
+## Using environment variables for your Project ID
+
+Rather than hardcoding your Project ID, use Nuxt's [runtime config](https://nuxt.com/docs/guide/going-further/runtime-config).
+
+**1. Add to your `nuxt.config.ts`:**
+
+```ts
+export default defineNuxtConfig({
+ runtimeConfig: {
+ public: {
+ swetrixPid: '',
+ },
+ },
+})
+```
+
+**2. Set the environment variable:**
+
+```
+NUXT_PUBLIC_SWETRIX_PID=YOUR_PROJECT_ID
+```
+
+**3. Reference it in your plugin:**
+
+```ts
+const config = useRuntimeConfig()
+Swetrix.init(config.public.swetrixPid)
+```
+
+## Further reading
+
+- [Vue integration](/vue-integration) β€” if you're using plain Vue without Nuxt, follow this guide instead.
+- [Tracking script reference](/swetrix-js-reference) β€” full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.
+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β€” package details and changelog.
diff --git a/docs/docs/integrations/vue.md b/docs/docs/integrations/vue.md
new file mode 100644
index 000000000..c3b9fab0d
--- /dev/null
+++ b/docs/docs/integrations/vue.md
@@ -0,0 +1,249 @@
+---
+title: Vue
+slug: /vue-integration
+---
+
+Integrate Swetrix with your [Vue](https://vuejs.org/) application to track page views, monitor errors, and capture custom events β€” all while staying privacy-friendly and GDPR-compliant.
+
+This guide covers Vue 3 apps built with **Vite** (the recommended tooling). If you're using a Vue framework, see the dedicated guide for [Nuxt](/nuxt-integration) instead.
+
+## Installation
+
+Install the Swetrix npm package:
+
+```bash
+npm install swetrix
+```
+
+### Basic setup (single-page apps without routing)
+
+If your app doesn't use client-side routing, you can initialise Swetrix once in your entry point.
+
+Open `src/main.ts` (or `src/main.js`):
+
+```ts
+import { createApp } from 'vue'
+import * as Swetrix from 'swetrix'
+import App from './App.vue'
+
+Swetrix.init('YOUR_PROJECT_ID')
+Swetrix.trackViews()
+
+createApp(App).mount('#app')
+```
+
+:::caution
+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.
+:::
+
+### With Vue Router
+
+Most Vue SPAs use [Vue Router](https://router.vuejs.org/) for client-side navigation. Since page transitions don't trigger full page loads, you need to call `trackViews()` on every route change.
+
+**1. Create a router plugin**
+
+Create `src/plugins/swetrix.ts`:
+
+```ts
+import type { App } from 'vue'
+import type { Router } from 'vue-router'
+import * as Swetrix from 'swetrix'
+
+export function swetrixPlugin(app: App, router: Router) {
+ Swetrix.init('YOUR_PROJECT_ID')
+ Swetrix.trackViews()
+
+ router.afterEach(() => {
+ Swetrix.trackViews()
+ })
+}
+```
+
+**2. Register it in your entry point**
+
+Update `src/main.ts`:
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+import { swetrixPlugin } from './plugins/swetrix'
+
+const app = createApp(App)
+
+app.use(router)
+swetrixPlugin(app, router)
+
+app.mount('#app')
+```
+
+### Noscript fallback (optional)
+
+To track visitors who have JavaScript disabled, add a noscript image pixel to your `index.html`:
+
+```html
+<body>
+ <div id="app"></div>
+
+ <noscript>
+ <img
+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"
+ alt=""
+ referrerpolicy="no-referrer-when-downgrade"
+ />
+ </noscript>
+</body>
+```
+
+## Disable tracking in development
+
+By default, Swetrix ignores `localhost` traffic. You can also explicitly disable it based on your environment:
+
+```ts
+Swetrix.init('YOUR_PROJECT_ID', {
+ disabled: import.meta.env.DEV,
+})
+```
+
+:::tip
+If you want to verify tracking locally during development, set `devMode: true` instead:
+
+```ts
+Swetrix.init('YOUR_PROJECT_ID', {
+ devMode: true,
+})
+```
+
+Remember to remove this before deploying to production.
+:::
+
+## Check your installation
+
+Build and deploy your application (or temporarily enable `devMode`) and visit a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.
+
+## Error tracking
+
+Enable automatic client-side error monitoring by adding `trackErrors()` to your initialisation. This captures unhandled JavaScript errors and reports them to Swetrix.
+
+Update your plugin:
+
+```ts
+Swetrix.init('YOUR_PROJECT_ID')
+Swetrix.trackViews()
+Swetrix.trackErrors()
+```
+
+Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.
+
+## Tracking custom events
+
+Custom events let you track specific user interactions β€” button clicks, form submissions, sign-ups, purchases, and more. Import `swetrix` in any component and call `track()`.
+
+### Example: tracking button clicks
+
+```vue
+<script setup lang="ts">
+import * as Swetrix from 'swetrix'
+
+function handleClick() {
+ Swetrix.track({
+ ev: 'SIGNUP_CTA_CLICK',
+ meta: {
+ location: 'navbar',
+ },
+ })
+}
+</script>
+
+<template>
+ <button @click="handleClick">Sign up</button>
+</template>
+```
+
+### Example: tracking form submissions
+
+```vue
+<script setup lang="ts">
+import * as Swetrix from 'swetrix'
+
+function handleSubmit() {
+ Swetrix.track({
+ ev: 'CONTACT_FORM_SUBMITTED',
+ meta: {
+ source: 'support_page',
+ },
+ })
+
+ // ...submit logic
+}
+</script>
+
+<template>
+ <form @submit.prevent="handleSubmit">
+ <input type="email" placeholder="[email protected]" required />
+ <textarea placeholder="How can we help?" required />
+ <button type="submit">Send</button>
+ </form>
+</template>
+```
+
+### Example: tracking outbound links
+
+Create a reusable component for external links. Save as `src/components/TrackedLink.vue`:
+
+```vue
+<script setup lang="ts">
+import * as Swetrix from 'swetrix'
+
+const props = withDefaults(
+ defineProps<{
+ href: string
+ eventName?: string
+ }>(),
+ {
+ eventName: 'OUTBOUND_CLICK',
+ },
+)
+
+function handleClick() {
+ Swetrix.track({
+ ev: props.eventName,
+ meta: { url: props.href },
+ })
+}
+</script>
+
+<template>
+ <a :href="href" target="_blank" rel="noopener noreferrer" @click="handleClick">
+ <slot />
+ </a>
+</template>
+```
+
+### Event naming rules
+
+Event names must:
+
+- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)
+- Be fewer than 64 characters
+- Start with an English letter
+
+We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `SIGNUP_CTA_CLICK`, `CONTACT_FORM_SUBMITTED`).
+
+## Using environment variables for your Project ID
+
+Rather than hardcoding your Project ID, you can use an environment variable. With Vite, prefix with `VITE_`:
+
+```
+VITE_SWETRIX_PID=YOUR_PROJECT_ID
+```
+
+```ts
+Swetrix.init(import.meta.env.VITE_SWETRIX_PID)
+```
+
+## Further reading
+
+- [Nuxt integration](/nuxt-integration) β€” if you're using Nuxt, follow the dedicated guide instead.
+- [Tracking script reference](/swetrix-js-reference) β€” full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.
+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β€” package details and changelog.
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 306732f5a..754ecd800 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -34,6 +34,11 @@ module.exports = {
'integrations/shopify',
'integrations/squarespace',
'integrations/sveltekit',
+ {
+ type: 'category',
+ label: 'Vue',
+ items: ['integrations/vue', 'integrations/nuxt'],
+ },
'integrations/thrivecart',
'integrations/webflow',
'integrations/wix',