site-vigil-visitors

Lightweight browser visit tracking with an optional React wrapper.

Features

• small browser-side tracker
• configurable siteId and endpoint
• uses navigator.sendBeacon() when available
• optional beforeunload leave event
• framework-agnostic core API
• React wrapper available via site-vigil-visitors/react

Installation

npm install site-vigil-visitors

For React projects:

npm install react site-vigil-visitors

Automated setup (React)

After installing, run:

npx site-vigil-visitors init

This prompts for your site ID, then adds the import and the <SiteVigil /> component to your app entry file (src/App.tsx, src/App.jsx, src/main.tsx, or src/main.jsx). To skip the prompt:

npx site-vigil-visitors init --site-id=my-site

Running init again is safe — it does nothing if the snippet is already there.

npm runs install scripts non-interactively, so the setup cannot prompt for a site ID during npm install itself. Always run init as a separate step.

Uninstalling

Run the removal command before uninstalling the package (it needs the package to still be installed):

npx site-vigil-visitors remove
npm uninstall site-vigil-visitors

remove scans every file under src/ and strips all tracking code: import statements referencing this package and any <SiteVigil /> elements (single- or multi-line, either quote style), including the legacy <Tracking /> name used before v0.3.0. If a file still references the package in a way it cannot safely remove (for example custom createTracker usage), it lists that file for manual review.

npm 7+ no longer runs preuninstall scripts, so the package cannot clean up automatically when you run npm uninstall — the remove command is the supported way to do it.

Quick start

React

import { SiteVigil } from 'site-vigil-visitors/react'

export function App() {
  return (
    <SiteVigil
      siteId="my-site"
      endpoint="https://t.site-vigil.com"
    />
  )
}

Plain JavaScript / TypeScript

import { createTracker } from 'site-vigil-visitors'

const tracker = createTracker({
  siteId: 'my-site',
  endpoint: 'https://t.site-vigil.com',
})

tracker.start()

Core usage

import { createTracker } from 'site-vigil-visitors'

const tracker = createTracker({
  siteId: 'my-site',
  endpoint: 'https://t.site-vigil.com',
})

tracker.start()
tracker.trackEvent('cta_click', { label: 'Register' })

React usage

import { SiteVigil } from 'site-vigil-visitors/react'

export function App() {
  return (
    <>
      <SiteVigil
        siteId="my-site"
        endpoint="https://t.site-vigil.com"
      />
      <main>Hello world</main>
    </>
  )
}

Small demo app

Here is a minimal Vite + React example using the package:

import { SiteVigil } from 'site-vigil-visitors/react'

export default function App() {
  return (
    <div>
      <SiteVigil
        siteId="demo-site"
        endpoint="https://t.site-vigil.com"
      />

      <h1>Visit Tracker Demo</h1>
      <button
        onClick={() => {
          console.log('CTA clicked')
        }}
      >
        Click me
      </button>
    </div>
  )
}

If you want manual event tracking in the same app:

import { createTracker } from 'site-vigil-visitors'

const tracker = createTracker({
  siteId: 'demo-site',
  endpoint: 'https://t.site-vigil.com',
})

tracker.trackEvent('button_click', { button: 'hero-cta' })

Next.js example

Use the React wrapper inside a client component:

'use client'

import { SiteVigil } from 'site-vigil-visitors/react'

export default function TrackingClient() {
  return (
    <SiteVigil
      siteId="next-app"
      endpoint="https://t.site-vigil.com"
    />
  )
}

Then include it in your app layout or page.

Plain JavaScript example

<script type="module">
  import { createTracker } from 'site-vigil-visitors'

  const tracker = createTracker({
    siteId: 'marketing-site',
    endpoint: 'https://t.site-vigil.com',
  })

  tracker.start()

  document.getElementById('cta')?.addEventListener('click', () => {
    tracker.trackEvent('cta_click', { location: 'hero' })
  })
</script>

API

createTracker(config)

Config options:

• siteId: string — unique identifier for the website/app
• endpoint: string — tracking endpoint URL
• sessionKey?: string — session storage key, defaults to tithij_session
• includeLeaveEvent?: boolean — whether to send a leave event on unload, defaults to true

Returned methods:

• start() — sends the initial visit event and binds unload tracking
• destroy() — removes unload tracking
• trackPageView() — manually sends a visit event
• trackEvent(action, metadata?) — sends a custom event

Local development

From the package folder:

npm install
npm run build
npm test

To preview what will be published:

npm run pack:check

Publishing

1. Update the version in package.json
2. Verify the package:

   npm test
   npm run pack:check

3. Publish to npm:

   npm publish --access public

Notes

• This package is intended for browser environments.
• In React development mode with StrictMode, effects may run twice.