Analytics

Integrate explicit analytics backends with a small shared runtime API.

Use Analytics to send app-owned events through a small shared runtime API while letting each backend keep its own transport model.

vercel maps browser calls to @vercel/analytics and server calls to @vercel/analytics/server.
cloudflare-analytics-engine always ingests browser-side helpers through ViteHub's generated route, then writes normalized events into a Cloudflare Analytics Engine dataset.

Nitro and Nuxt use the same runtime helpers and add a server route only for backends that need first-party ingestion.

Getting started

Install the package

Install @vitehub/analytics and only the backend SDK you actually need.

Terminal

pnpm add https://pkg.pr.new/vite-hub/vitehub/@vitehub/analytics@main @vercel/analytics

analytics.provider is required. Keep backend-specific settings under analytics.vercel or analytics.cloudflareAnalyticsEngine. Use analytics.client.base only when you want to change the generated first-party ingestion route.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@vitehub/analytics/nuxt'],
  analytics: {
    provider: 'vercel',
    vercel: {
      mode: 'auto',
    },
  },
})

Define an event

Analytics definitions live in analytics/ at the project root. When your app uses srcDir, ViteHub also scans src/analytics/.

analytics/signup.ts

import { defineTrack } from '@vitehub/analytics'

export default defineTrack<{ plan: 'free' | 'pro' }>((input) => ({
  props: {
    plan: input.plan,
  },
}), {
  label: 'Signup',
  runtimes: ['client', 'server'],
})

Track the event

Call the public runtime helper with the discovered definition name. ViteHub applies the optional label and transform() from the definition before it reaches the active backend.

server/api/signup.post.ts

import { track } from '@vitehub/analytics'

export default defineEventHandler(async () => {
  await track('signup', {
    plan: 'pro',
  })

  return { ok: true }
})

Backend model

ViteHub keeps one event API but does not force every backend into the same ingestion path.

Backend	Browser path	Server path
`vercel`	Official Vercel browser SDK	`@vercel/analytics/server`
`cloudflare-analytics-engine`	Generated `/_vitehub/analytics/track` route	Cloudflare Analytics Engine binding

Runtime API

The package root exposes a deliberately small surface.

Export	Use it for
`defineTrack(transform, options?)`	Define a file-based analytics event.
`createTrack(options?)(transform)`	Define the same event with options first.
`track(name, data?)`	Emit a custom event by discovered name.
`page(data?)`	Emit a page event when the active backend supports it.
`identify(userId, traits?)`	Associate traits with the active user.
`alias(previousId, userId?)`	Alias one identity to another.
`group(groupId, traits?)`	Associate the active user with a group.
`reset()`	Clear the active identity when the backend supports it.
`getAnalytics()`	Resolve the active backend handle and capability flags.

Definition options

Definition options stay portable on purpose.

Option	Use it for
`label`	Replace the default event label derived from the file name.
`runtimes`	Restrict the definition to `client`, `server`, or both.

transform() should return an object. When it returns { props }, Analytics forwards props as the backend payload.

Choose a backend

Vercel Analytics

Configure Vercel Analytics through the official SDK and keep the shared ViteHub runtime API.

Cloudflare Analytics Engine

Configure first-party analytics ingestion on Cloudflare and write events into an Analytics Engine dataset.

Report an issue or Edit this page on GitHub

Local

Run sandboxes locally with OS-level isolation using platform primitives.

Vercel

Configure Vercel Analytics through the official SDK and keep a small portable runtime API.