Vue.js SDK

The Vue.js SDK provides seamless analytics for Vue 3 applications with automatic route tracking via Vue Router, composables, and TypeScript support.

The Vue SDK (@sparklytics/vue) is currently in development. This page describes the planned API. For now, use the HTML snippet for Vue projects.

Installation

npm install @sparklytics/vue

Setup

Install the plugin

Add the Sparklytics plugin to your Vue app:

main.ts

import { createApp } from 'vue'
import { createSparklytics } from '@sparklytics/vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)

app.use(createSparklytics({
  host: 'https://analytics.example.com',
  websiteId: 'YOUR_WEBSITE_ID',
  router // Pass your Vue Router instance for automatic tracking
}))

app.use(router)
app.mount('#app')

Track custom events with composables

Use the useSparklytics composable in your components:

SignupButton.vue

<script setup lang="ts">
import { useSparklytics } from '@sparklytics/vue'

const { track } = useSparklytics()

const handleSignup = () => {
  track('signup_click', { plan: 'pro' })
  // ... your signup logic
}
</script>

<template>
  <button @click="handleSignup">
    Get Started
  </button>
</template>

Verify tracking

Navigate between routes. Pageviews should appear in the Sparklytics dashboard automatically.

Configuration Options

Configure the plugin when installing:

main.ts

import { createSparklytics } from '@sparklytics/vue'
import router from './router'

app.use(createSparklytics({
  host: 'https://analytics.example.com',
  websiteId: 'abc123',
  router, // Required for automatic pageview tracking
  disabled: import.meta.env.DEV, // Disable in development
  respectDnt: true, // Respect DNT/GPC signals
  excludeHash: false, // Track hash changes
  trackLinks: 'outbound', // Track outbound link clicks
  trackScrollDepth: [25, 50, 75, 100], // Track scroll milestones
  trackForms: true // Track form submissions
}))

Plugin Options

Option	Type	Required	Description
`host`	`string`	Yes	Your Sparklytics server URL
`websiteId`	`string`	Yes	Website ID from dashboard
`router`	`Router`	Recommended	Vue Router instance for auto-tracking
`disabled`	`boolean`	No	Disable all tracking
`respectDnt`	`boolean`	No	Respect DNT/GPC signals (default: `true`)
`excludeHash`	`boolean`	No	Skip hash-only route changes
`trackLinks`	`boolean \| "outbound"`	No	Track link clicks
`trackScrollDepth`	`boolean \| number[]`	No	Track scroll milestones
`trackForms`	`boolean`	No	Track form submissions

Tracking Custom Events

Use the useSparklytics composable to access the tracking API:

Composition API
Options API
Template Ref

ProductCard.vue

<script setup lang="ts">
import { useSparklytics } from '@sparklytics/vue'

const props = defineProps<{
  product: {
    id: string
    name: string
    price: number
  }
}>()

const { track } = useSparklytics()

const addToCart = () => {
  track('add_to_cart', {
    product_id: props.product.id,
    product_name: props.product.name,
    price: props.product.price,
    currency: 'USD'
  })
  // ... add to cart logic
}
</script>

<template>
  <button @click="addToCart">
    Add to Cart - ${{ product.price }}
  </button>
</template>

NewsletterForm.vue

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    handleSubmit() {
      this.$sparklytics.track('newsletter_signup')
      // ... submit logic
    }
  }
})
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <input type="email" placeholder="Your email" />
    <button type="submit">Subscribe</button>
  </form>
</template>

DownloadButton.vue

<script setup lang="ts">
import { useSparklytics } from '@sparklytics/vue'

const { track } = useSparklytics()

const handleDownload = (filename: string) => {
  track('file_download', { filename })
}
</script>

<template>
  <a 
    href="#" 
    download
    @click="handleDownload('file.pdf')"
  >
    Download File
  </a>
</template>

Visitor Identification

Identify logged-in users to track their journey across sessions:

<script setup lang="ts">
import { useSparklytics } from '@sparklytics/vue'
import { useRouter } from 'vue-router'

const router = useRouter()
const { identify } = useSparklytics()

const handleLogin = async (userId: string) => {
  // After successful login
  identify(userId)
  router.push('/dashboard')
}
</script>

<template>
  <LoginForm @submit="handleLogin" />
</template>

TypeScript Support

The SDK provides full TypeScript support. Define custom event types:

types/analytics.ts

import type { UseSparklytics } from '@sparklytics/vue'

type CustomEvents = 
  | { name: 'signup_click', data: { plan: 'free' | 'pro' | 'enterprise' } }
  | { name: 'add_to_cart', data: { product_id: string, price: number } }
  | { name: 'newsletter_signup', data?: never }

export function useTypedAnalytics(): UseSparklytics<CustomEvents> {
  return useSparklytics<CustomEvents>()
}

PricingCard.vue

<script setup lang="ts">
import { useTypedAnalytics } from '@/types/analytics'

const { track } = useTypedAnalytics()

const selectPlan = (plan: 'free' | 'pro' | 'enterprise') => {
  track('signup_click', { plan }) // Fully typed!
}
</script>

<template>
  <button @click="selectPlan('pro')">
    Choose Pro Plan
  </button>
</template>

Environment Variables

Use Vite environment variables:

.env

VITE_SPARKLYTICS_HOST=https://analytics.example.com
VITE_SPARKLYTICS_WEBSITE_ID=your-website-id

main.ts

import { createSparklytics } from '@sparklytics/vue'

app.use(createSparklytics({
  host: import.meta.env.VITE_SPARKLYTICS_HOST,
  websiteId: import.meta.env.VITE_SPARKLYTICS_WEBSITE_ID,
  router
}))

Vue Router Integration

When you pass your Router instance to the plugin, pageviews are tracked automatically on every route change:

router/index.ts

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: Home },
    { path: '/pricing', component: Pricing },
    { path: '/about', component: About }
  ]
})

export default router

main.ts

import { createSparklytics } from '@sparklytics/vue'
import router from './router'

app.use(createSparklytics({
  host: 'https://analytics.example.com',
  websiteId: 'abc123',
  router // Automatic pageview tracking enabled
}))

The SDK automatically captures route meta fields like title if defined in your route configuration.

Nuxt 3 Support

For Nuxt 3, use the Nuxt module (coming soon):

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@sparklytics/nuxt'],
  sparklytics: {
    host: 'https://analytics.example.com',
    websiteId: 'abc123'
  }
})

Alternatively, use the HTML snippet in app.vue:

app.vue

<template>
  <div>
    <NuxtPage />
  </div>
</template>

<script setup>
useHead({
  script: [
    {
      defer: true,
      src: 'https://analytics.example.com/s.js',
      'data-website-id': 'abc123'
    }
  ]
})
</script>

Performance

Bundle size: < 5 KB gzipped
Tree-shakeable: Unused features are removed
Zero runtime overhead: Async tracking
SSR compatible: Works with Nuxt 3 and other SSR frameworks

Migration from HTML Snippet

If you’re currently using the HTML snippet, migration is simple:

Remove the script tag

Delete the <script> tag from index.html:

- <script defer src="https://analytics.example.com/s.js" data-website-id="abc123"></script>

Install the Vue SDK

npm install @sparklytics/vue

Replace window.sparklytics calls

- window.sparklytics?.track('signup_click', { plan: 'pro' })
+ const { track } = useSparklytics()
+ track('signup_click', { plan: 'pro' })

Get Started

Core Features

Integrations

Configuration

Self-Hosting

Installation

Setup

Configuration Options

Plugin Options

Tracking Custom Events

Visitor Identification

TypeScript Support

Environment Variables

Vue Router Integration

Nuxt 3 Support

Performance

Migration from HTML Snippet

Next Steps

HTML Snippet

Custom Integration

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Configuration

Self-Hosting

​Installation

​Setup

​Configuration Options

​Plugin Options

​Tracking Custom Events

​Visitor Identification

​TypeScript Support

​Environment Variables

​Vue Router Integration

​Nuxt 3 Support

​Performance

​Migration from HTML Snippet

​Next Steps

HTML Snippet

Custom Integration

Build docs developers (and LLMs) love

Installation

Setup

Configuration Options

Plugin Options

Tracking Custom Events

Visitor Identification

TypeScript Support

Environment Variables

Vue Router Integration

Nuxt 3 Support

Performance

Migration from HTML Snippet

Next Steps