Client API Overview

The client API gives you programmatic control over the tracker from within your application code. It is available via the @ndriadev/vite-plugin-monitor/client entry point.

import { tracker } from '@ndriadev/vite-plugin-monitor/client'

When Do You Need the Client API?

The auto-tracking features (clicks, HTTP, errors, navigation, console) require no client API imports. They are installed automatically by the setup script injected into index.html.

You need the client API when you want to:

Use case	API
Delay init until consent/auth	tracker.init()
Track custom business events	tracker.track()
Update user identity after login/logout	tracker.setUser()
Attach global metadata to all events	tracker.setContext()
Time an async operation	tracker.time() / tracker.timeEnd()
Group related events together	tracker.group()
Tear down the tracker (e.g. on logout)	tracker.destroy()

The tracker Proxy

The tracker export is a safe proxy. All method calls are silently dropped if the tracker has not been initialized yet (before tracker.init() is called, or in SSR/Node.js environments). This means you can safely call tracker.track() anywhere in your code without guarding with if (tracker).

// This is always safe — no error if called before init()
tracker.track('page:viewed', { path: '/home' })

Methods

Method	Description
tracker.init(userIdFn?)	Initialize the tracker. Safe to call multiple times (singleton).
tracker.track(name, data?, opts?)	Emit a custom event.
tracker.setUser(userId, opts?)	Update the user identity.
tracker.setContext(attrs)	Attach persistent metadata to all future events.
tracker.time(label)	Start a named timer.
tracker.timeEnd(label, data?, opts?)	Stop a timer and emit a custom event with durationMs.
tracker.group(name)	Generate a unique group ID for correlated events.
tracker.destroy()	Tear down the tracker completely.

TypeScript

The tracker object is fully typed. Import the ITrackerClient interface for type-checking:

import type { ITrackerClient } from '@ndriadev/vite-plugin-monitor'

Framework Integration Examples

React

// src/main.tsx
import { tracker } from '@ndriadev/vite-plugin-monitor/client'
import { useEffect } from 'react'
import { useAuth } from './hooks/useAuth'

function AuthSync() {
  const { user } = useAuth()

  useEffect(() => {
    if (user) {
      tracker.setUser(user.id, { attributes: { plan: user.plan } })
    } else {
      tracker.setUser(null)
    }
  }, [user])

  return null
}

Vue 3

// src/plugins/tracker.ts
import { tracker } from '@ndriadev/vite-plugin-monitor/client'
import { watch } from 'vue'
import { useUserStore } from '@/stores/user'

export function setupTrackerSync() {
  const userStore = useUserStore()

  watch(
    () => userStore.currentUser,
    (user) => {
      if (user) {
        tracker.setUser(user.id)
      } else {
        tracker.setUser(null)
      }
    },
    { immediate: true }
  )
}

Svelte

<script lang="ts">
import { tracker } from '@ndriadev/vite-plugin-monitor/client'
import { user } from './stores/auth'

$: if ($user) {
  tracker.setUser($user.id)
} else {
  tracker.setUser(null)
}
</script>