Praxor Analytics SDK

Type-safe product and pageview analytics for JavaScript and TypeScript web applications.

Install

npm install praxor

Quick start

Initialize Praxor once in browser code. You can find your site ID in the Praxor Analytics dashboard.

import { initPraxor } from "praxor";

const praxor = initPraxor({
  siteId: "your-site-id",
  autoCapturePageviews: true,
});

praxor.track("signup", { plan: "pro" });

Automatic pageviews include the initial load and client-side navigations made with pushState, replaceState, or the browser back and forward buttons.

Do not install the Praxor script tag and npm SDK together; each one captures pageviews independently.

Next.js / React

Create one client-only module and import it where you track events:

// lib/analytics.ts
import { initPraxor } from "praxor";

export const analytics = initPraxor({
  siteId: process.env.NEXT_PUBLIC_PRAXOR_SITE_ID!,
});

"use client";

import { analytics } from "@/lib/analytics";

export function SignupButton() {
  return <button onClick={() => analytics.track("signup")}>Sign up</button>;
}

initPraxor is safe to import during server rendering: it installs browser listeners only when window and document exist. Initialize it from browser code so automatic pageview capture begins after hydration.

Configuration

interface PraxorConfig {
  siteId: string;
  apiUrl?: string; // defaults to https://api.praxor.dev
  debug?: boolean;
  trackOutboundLinks?: boolean; // defaults to true
  autoCapturePageviews?: boolean | {
    trackHashChanges?: boolean; // defaults to false
    captureInitialPageview?: boolean; // defaults to true
    debounceMs?: number; // defaults to 100
  };
}

For local development or a self-hosted Praxor instance, set apiUrl to its public API origin:

initPraxor({ siteId: "your-site-id", apiUrl: "http://localhost:3001" });

Methods

track(name, properties?)

praxor.track("checkout_started", {
  plan: "pro",
  billing: "yearly",
});

trackPageview(path?)

Use manual pageviews when automatic capture is disabled or when you need to provide an explicit path.

const praxor = initPraxor({
  siteId: "your-site-id",
  autoCapturePageviews: false,
});

await praxor.trackPageview();
await praxor.trackPageview("/pricing");

getVisitorId()

Returns the visitor ID after the first pageview request completes. Attach this value as praxorVisitorId to payment metadata to attribute revenue.

const visitorId = praxor.getVisitorId();

destroy()

Removes the navigation and outbound-link listeners installed by this client.

Singleton helpers

initPraxor(config) returns the same application-wide client on later calls. Access it from another module with getPraxorClient(). Use createPraxorClient(config) when you explicitly need an independent client, and resetPraxor() for tests or hot-module reload cleanup.