Installation

Install @poluruprvn/pug-web and wire it into your framework. The SDK is ESM-only and runs in the browser.

npm


npm install @poluruprvn/pug-web

pnpm / yarn


pnpm add @poluruprvn/pug-web
# or
yarn add @poluruprvn/pug-web

Import

The SDK is ESM-only. Import from the package root:


import { init, track, identify, reset } from '@poluruprvn/pug-web'

Framework setup

Vite + React


// src/main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { init } from '@poluruprvn/pug-web'
import App from './App'
 
init(import.meta.env.VITE_PUG_PROJECT_ID, {
  apiKey: import.meta.env.VITE_PUG_API_KEY,
  endpoint: 'https://api.pug.sh'
})
 
createRoot(document.getElementById('root')!).render(
  <StrictMode><App /></StrictMode>
)


# .env
VITE_PUG_PROJECT_ID=your-project-id
VITE_PUG_API_KEY=your-sdk-api-key

Next.js App Router

Create a client provider component — init must run in the browser, not during SSR:


// components/PugProvider.tsx
'use client'
 
import { init } from '@poluruprvn/pug-web'
import { useEffect } from 'react'
 
export function PugProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    init(process.env.NEXT_PUBLIC_PUG_PROJECT_ID!, {
      apiKey: process.env.NEXT_PUBLIC_PUG_API_KEY!,
      endpoint: 'https://api.pug.sh'
    })
  }, [])
 
  return <>{children}</>
}


// app/layout.tsx
import { PugProvider } from '@/components/PugProvider'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <PugProvider>{children}</PugProvider>
      </body>
    </html>
  )
}


# .env.local
NEXT_PUBLIC_PUG_PROJECT_ID=your-project-id
NEXT_PUBLIC_PUG_API_KEY=your-sdk-api-key

Track page views in a client component that responds to route changes:


// components/PugPageView.tsx
'use client'
 
import { track } from '@poluruprvn/pug-web'
import { usePathname } from 'next/navigation'
import { useEffect } from 'react'
 
export function PugPageView() {
  const pathname = usePathname()
  useEffect(() => {
    track('page_view')
  }, [pathname])
  return null
}

Or disable the built-in page view tracker and manage routing yourself — see Auto-tracking.

Next.js Pages Router


// pages/_app.tsx
import { useEffect } from 'react'
import { useRouter } from 'next/router'
import { init, track } from '@poluruprvn/pug-web'
import type { AppProps } from 'next/app'
 
let initialized = false
 
export default function App({ Component, pageProps }: AppProps) {
  const router = useRouter()
 
  useEffect(() => {
    if (!initialized) {
      init(process.env.NEXT_PUBLIC_PUG_PROJECT_ID!, {
        apiKey: process.env.NEXT_PUBLIC_PUG_API_KEY!,
        endpoint: 'https://api.pug.sh'
      })
      initialized = true
    }
  }, [])
 
  useEffect(() => {
    const handleRouteChange = () => track('page_view')
    router.events.on('routeChangeComplete', handleRouteChange)
    return () => router.events.off('routeChangeComplete', handleRouteChange)
  }, [router.events])
 
  return <Component {...pageProps} />
}

Vue 3


// main.ts
import { createApp } from 'vue'
import { init } from '@poluruprvn/pug-web'
import App from './App.vue'
import router from './router'
 
init(import.meta.env.VITE_PUG_PROJECT_ID, {
  apiKey: import.meta.env.VITE_PUG_API_KEY,
  endpoint: 'https://api.pug.sh'
})
 
const app = createApp(App)
app.use(router)
app.mount('#app')

Requirements

Modern browsers with fetch and localStorage
HTTPS in production
Connect RPC-compatible endpoint

Verify installation

After installing, run your app and check Live in the dashboard. Auto-tracked page_view events should appear within 15 seconds.

Common issues

Symptom	Fix
`init is not a function`	Ensure ESM import, not `require()`
Events during SSR	Wrap init in `useEffect` or client-only component
Module not found	Confirm package installed: `npm ls @poluruprvn/pug-web`
Double page_view events	Disable auto page view tracker if tracking manually

Next step

Initialization — configure batching, sampling, and auto-trackers.