Install and use the Faurya npm package in your JavaScript or TypeScript applications, including React, Next.js, Vue, and Angular.

Faurya NPM SDK

Install Faurya as an npm package for type-safe analytics tracking in JavaScript and TypeScript applications. Perfect for React, Next.js, Vue, Angular, and other web frameworks.

Why use the SDK?

TypeScript support — Full type definitions for autocomplete and type safety
Tree-shakeable — Only import what you need
Framework agnostic — Works with React, Vue, Angular, Svelte, and vanilla JS
Automatic tracking — Built-in page view, session, and device tracking
Offline-ready — Queues events when offline and syncs when back online

Installation

npm install faurya

Quick Start

Basic setup

import { initFaurya } from "faurya";

// Initialize the SDK
const faurya = await initFaurya({
  websiteId: "your_website_id",
  domain: "yourdomain.com", // optional, defaults to current hostname
});

// Track page views
faurya.trackPageview();

// Track custom events
faurya.track("signup", { email: "user@example.com" });

// Identify users
faurya.identify("user_123", {
  email: "user@example.com",
  plan: "pro",
});

React / Next.js example

// lib/analytics.ts
import { initFaurya } from "faurya";

let faurya: any = null;

export async function getAnalytics() {
  if (!faurya) {
    faurya = await initFaurya({
      websiteId: "your_website_id",
      domain: "yourdomain.com",
    });
  }
  return faurya;
}

Then use it in your app:

// app/page.tsx or components/SignupButton.tsx
import { getAnalytics } from '@/lib/analytics';

export default function SignupButton() {
  const handleSignup = async () => {
    const faurya = await getAnalytics();
    faurya.track('signup', { plan: 'pro' });
  };
  return <button onClick={handleSignup}>Sign Up</button>;
}

Automatic page view tracking in Next.js

Track page views automatically on route changes:

// app/layout.tsx or pages/_app.tsx
'use client';

import { useEffect } from 'react';
import { usePathname } from 'next/navigation';
import { getAnalytics } from '@/lib/analytics';

export default function RootLayout({ children }) {
  const pathname = usePathname();

  useEffect(() => {
    getAnalytics().then((faurya) => faurya.trackPageview());
  }, [pathname]);

  return <html><body>{children}</body></html>;
}

Configuration Options

interface FauryaWebConfig {
  websiteId: string; // Required: Your Faurya website ID
  domain?: string; // Optional: your domain
  debug?: boolean; // Optional: Enable console logs (default: false)
  disabled?: boolean; // Optional: Disable tracking (default: false)
  apiUrl?: string; // Optional: Custom API endpoint
  maxQueueSize?: number; // Optional: Max queue size before flush (default: 10)
}

API Methods

Track custom events

// Simple event
faurya.track("button_click");

// Event with custom data
faurya.track("purchase", {
  amount: 99.99,
  currency: "USD",
  product: "Premium Plan",
});

Track page views

// Track current page
faurya.trackPageview();

// Track specific URL
faurya.trackPageview("/custom/path");

// Track with custom data
faurya.trackPageview("/pricing", {
  experiment: "pricing-test-v2",
});

Identify users

// Simple identification
faurya.identify("user_123");

// With user properties
faurya.identify("user_123", {
  email: "user@example.com",
  plan: "pro",
  company: "Acme Inc",
  signup_date: "2024-01-15",
});

Flush events manually

// Force send all queued events immediately
await faurya.flush();

Reset the client

Clear visitor ID and session (useful for logout):

faurya.reset();

TypeScript Support

All packages include full TypeScript definitions:

import type { FauryaClient, FauryaConfig, TrackEventData } from "faurya";

const config: FauryaConfig = {
  websiteId: "your_website_id",
  debug: true,
};

Troubleshooting

Events not showing up?

Check your websiteId is correct
Enable debug: true to see console logs
Verify your domain matches your Faurya dashboard settings
Check network requests in browser DevTools

TypeScript errors?

Ensure you're using TypeScript 5.0+
Run npm install @types/node if needed

Need help? Email us at team@faurya.com

NPM SDK / Package