NPM module (@pageviews/tracker)

The @pageviews/tracker NPM module is the recommended way to integrate Pageviews into JavaScript frameworks like React, Vue, Next.js, Nuxt, and other single-page applications. It gives you full programmatic control over tracking with proper lifecycle management and TypeScript support.

Installation

npm install @pageviews/tracker

Quick start

Initialize the tracker once in your app's entry point, then use track() anywhere:

import { init, track, identify } from '@pageviews/tracker'

// Initialize once (typically in your app entry point)
await init({ siteId: 'your-site-id' })

// Track custom events
track('signup', { props: { plan: 'pro' } })

// Track events with revenue
track('Purchase', { revenue: { amount: 49.99, currency: 'USD' } })

// Identify users for Realtime User Explorer
identify({ userId: 'john@example.com' })

API reference

init(options)

Initializes the tracker. Must be called before track() or identify(). Can only be called once unless destroy() is called first.

• siteId (required) — Your site ID from the Pageviews dashboard.
• endpoint (optional) — Custom ingest API endpoint. Default: https://data.pageviews.ai.

On init, the module fetches your site configuration (cached in localStorage for 1 hour), sends the initial pageview, and starts listening for SPA navigations and engagement.

track(eventName, options?)

Sends a custom event.

• eventName (required) — The event name (must match a goal in your dashboard).
• options.props — Custom properties as key-value pairs (string, number, or boolean values).
• options.revenue — Attach revenue data to this event. Object with amount (positive number, max 1 billion) and currency (ISO 4217 code, e.g. USD). The event name must match a goal with revenue tracking enabled.
• options.url — Override the page URL for this event.
• options.callback — Called when the event is sent or ignored.

// Custom event with properties
track('signup', { props: { plan: 'pro' } })

// Event with revenue
track('Purchase', {
    revenue: { amount: 49.99, currency: 'USD' },
    props: { product: 'Pro Plan' }
})

identify(data)

Associates a custom identifier with the current visitor session. This data appears in the Realtime User Explorer and is never persisted to the database. The identifier is stored in Redis with a 24-hour TTL — it is intentionally ephemeral for GDPR compliance.

• userId (required) — A unique identifier for the user (e.g. email, username, or internal ID).

identify({ userId: 'john@example.com' })

destroy()

Stops all tracking, removes event listeners, and resets state. After calling destroy(), you can call init() again.

Framework examples

React

// app/layout.tsx — wrap your app with an analytics provider
import { useEffect } from 'react'
import { init, destroy } from '@pageviews/tracker'

export function AnalyticsProvider({ children, siteId }) {
    useEffect(() => {
        init({ siteId })
        return () => destroy()
    }, [siteId])
    return children
}

// In any component
import { track } from '@pageviews/tracker'

function SignupButton() {
    return <button onClick={() => track('signup')}>Sign up</button>
}

Vue

// main.js or a plugin file
import { init } from '@pageviews/tracker'
init({ siteId: 'your-site-id' })

// In any component
import { track } from '@pageviews/tracker'

function handleClick() {
    track('button_click', { props: { button: 'cta' } })
}

Next.js (App Router)

// app/providers.tsx — 'use client'
import { useEffect } from 'react'
import { init, destroy } from '@pageviews/tracker'

export function Providers({ children }) {
    useEffect(() => {
        init({ siteId: 'your-site-id' })
        return () => destroy()
    }, [])
    return <>{children}</>
}

What's tracked automatically

Once initialized, the module automatically tracks:

• Pageviews — Including client-side navigations in SPAs.
• Engagement — Active time and scroll depth, sent when navigating away or closing the tab.
• Outbound links — Clicks on external links (if enabled in dashboard settings).
• File downloads — Clicks on downloadable files (if enabled).
• Form submissions — Form submit events (if enabled).
• Scroll goals — Scroll depth thresholds configured in your goals.

These features are managed in your Site Settings in the Pageviews dashboard. The module fetches your configuration on init and caches it locally.

Opting out

Users can opt out of tracking by setting a flag in localStorage:

localStorage.setItem('pageviews_ignore', 'true')

When set, all track() and identify() calls are silently ignored.

Automatic exclusions

Tracking is automatically skipped for:

• Localhost — localhost, 127.x.x.x, [::1]
• Bots — Headless browsers (Puppeteer, Playwright, Cypress, etc.)
• Prerendered pages — Deferred until the page is actually viewed.
• Opted-out users — pageviews_ignore in localStorage.

TypeScript

The module ships with full type declarations. All types are exported:

import type { TrackOptions, IdentifyData, SiteConfig } from '@pageviews/tracker'