Quickstart

Send your first event to Pug in under five minutes. By the end of this guide you’ll have the Web SDK installed, a page_view flowing into your project, and confirmation in the dashboard.

Prerequisites

• A Pug account — sign up at app.pug.sh 
• Node.js 18+ and npm, pnpm, or yarn
• A web app or a blank Vite/Next.js project to test with

1. Create a project

1. Sign in to the dashboard .
2. Create an organization (or join an existing one).
3. Create a project inside that org.
4. Open Settings → API keys and copy your project ID and SDK API key.

Keep the SDK key in client-side code only. Never commit a shared/private key to a public repo.

2. Install the Web SDK

npm install @poluruprvn/pug-web

See Installation for pnpm, yarn, and framework-specific setup.

3. Initialize and track

Call init once at app startup, then track events anywhere in your app.

Vite / React

// src/main.tsx
import { init, track } from '@poluruprvn/pug-web'
 
init('YOUR_PROJECT_ID', {
  apiKey: 'YOUR_SDK_API_KEY',
  endpoint: 'https://api.pug.sh'
})
 
track('page_view')

Next.js App Router

Create a client component so init runs in the browser:

// components/PugProvider.tsx
'use client'
 
import { init, track } 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'
    })
    track('page_view')
  }, [])
 
  return <>{children}</>
}

Add PugProvider to your root layout. Store keys in .env.local:

NEXT_PUBLIC_PUG_PROJECT_ID=your-project-id
NEXT_PUBLIC_PUG_API_KEY=your-sdk-api-key

4. Verify in the dashboard

1. Open your project in the dashboard.
2. Go to Live — you should see an active visitor count increase within a few seconds.
3. Go to Events — page_view should appear in the catalog with a recent timestamp.

Events are batched client-side and flushed every few seconds, so allow up to 10 seconds for the first event to appear.

5. Identify a user (optional)

After sign-in, link anonymous activity to a known user:

import { identify } from '@poluruprvn/pug-web'
 
identify('user-123', { email: 'user@example.com', plan: 'pro' })

On sign-out, call reset() to start a fresh anonymous session. See Identity & sessions.

You’re done when…

• page_view appears in Live and Events
• Auto-tracked events (clicks, scrolls) appear if you left defaults enabled
• identify() merges pre-login events into a profile (optional)

Common issues

Next steps

• Core concepts — orgs, projects, and the event pipeline
• Initialization — batching, sampling, auto-track options
• Tracking events — custom events and well-known schemas
• Dashboard overview — KPI tiles and funnels