@pixby-analytics/analytics-sdk

Browser SDK for sending product analytics events to Pixby.

Install

Published package:

pnpm add @pixby-analytics/analytics-sdk

Local workspace package during development:

pnpm add /Users/aryankhan/Desktop/Work/pixby/sdk

Usage

import analytics from "@pixby-analytics/analytics-sdk";

analytics.init("demo_project_key", {
  apiUrl: "http://localhost:8080"
});

analytics.identify("user_1", {
  orgId: "org_1",
  role: "admin",
  plan: "pro"
});

analytics.track("project_created", {
  project_id: "123"
});

Web Script

For website installs without bundling the package into app code:

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@pixby-analytics/[email protected]/dist/web.global.js"
  data-project-key="demo_project_key"
  data-api-url="https://pixby-analytics.onrender.com"
></script>

The web bundle automatically:

• initializes the SDK from data-* attributes
• tracks the initial page_viewed
• tracks SPA route changes through pushState, replaceState, popstate, and hashchange
• tracks Core Web Vitals: LCP, INP, CLS, FCP, and TTFB
• exposes window.pixbyAnalytics for optional manual tracking

Web Vitals are sent as web_vital_measured events with metric, value, rating, unit, path, url, and title properties. The dashboard aggregates these into p75 field metrics for each web analytics project.

API

init(projectKey, options?)

Initializes the client and starts the background flush loop.

Options:

• apiUrl
• flushIntervalMs
• flushAt
• storageKey
• headers

identify(userId, traits?)

Associates future events with a known user and event-time traits.

track(event, properties?, context?)

Queues an event for delivery.

flush()

Immediately attempts to send queued events.

Build

pnpm --filter @pixby-analytics/analytics-sdk build

The package outputs:

• dist/index.js for ESM consumers
• dist/index.cjs for CommonJS consumers
• dist/index.d.ts for TypeScript

Versioning and publish flow

Create a changeset:

pnpm changeset

Review version updates:

pnpm version:sdk

Publish:

pnpm release:sdk

Dry-run the package before publishing:

pnpm --filter @pixby-analytics/analytics-sdk pack:check
pnpm --filter @pixby-analytics/analytics-sdk publish:dry-run

The dry-run script uses a temporary npm cache under /tmp so it can succeed even if your local ~/.npm cache has permission issues.

Real npm publish checklist

1. Log into npm:

npm login

2. Confirm the package name you want is available:

npm view @pixby-analytics/analytics-sdk

3. Build and inspect the tarball:

pnpm --filter @pixby-analytics/analytics-sdk pack:check

4. Run a publish dry run:

pnpm --filter @pixby-analytics/analytics-sdk publish:dry-run

5. Publish for real:

cd sdk
npm publish --access public

Notes before public publish

• The SDK is licensed under MIT.
• If you want richer npm metadata later, add repository, homepage, and bugs fields once the public repo URL is final.

Next.js example

App Router client bootstrap:

"use client";

import { useEffect } from "react";
import analytics from "@pixby-analytics/analytics-sdk";

export function PixbyProvider() {
  useEffect(() => {
    analytics.init(process.env.NEXT_PUBLIC_PIXBY_PROJECT_KEY!, {
      apiUrl: process.env.NEXT_PUBLIC_PIXBY_API_URL
    });
  }, []);

  return null;
}

Mount the provider near the root layout and call identify() and track() from client components after user or feature actions are known.