Node.js SDK

The @entrolytics/node-client package provides server-side analytics tracking for Node.js applications.

Installation

pnpm add @entrolytics/node-client

Quick Start

Install Package

pnpm add @entrolytics/node

Create Client

import { Entrolytics } from '@entrolytics/node'

const client = new Entrolytics({
  websiteId: 'your-website-id',
  hostUrl: 'https://entrolytics.dev'
})

Track Events

// Track page view
await client.trackPageView({
  url: '/dashboard',
  title: 'Dashboard',
  referrer: 'https://google.com'
})

// Track custom event
await client.trackEvent({
  url: '/products',
  name: 'add_to_cart',
  data: {
    productId: 'prod_123',
    price: 29.99,
    currency: 'USD'
  }
})

// Identify user/session
await client.identify({
  sessionId: 'session_abc123',
  userId: 'user_456',
  plan: 'premium'
})

Configuration

const client = new Entrolytics({
  // Required
  websiteId: 'your-website-id',
  hostUrl: 'https://entrolytics.dev',

  // Optional
  sessionId: 'custom-session-id',
  userAgent: 'MyApp/1.0',
  timeout: 10000,
  endpoint: 'standard' // 'standard' | 'edge' | 'native'
})

Configuration Options

Option	Type	Default	Description
`websiteId`	`string`	-	Your Entrolytics website ID (required)
`hostUrl`	`string`	-	Entrolytics host URL (required)
`sessionId`	`string`	-	Custom session identifier
`userAgent`	`string`	Auto-generated	Custom user agent for requests
`timeout`	`number`	`10000`	Request timeout in milliseconds
`endpoint`	`string`	`'standard'`	API endpoint: `'standard'`, `'edge'`, or `'native'`

API Reference

`trackPageView(options)`

Track a page view event.

await client.trackPageView({
  url: '/page-path',
  title: 'Page Title',
  referrer: 'https://...',
  hostname: 'example.com',
  language: 'en-US',
  screen: '1920x1080'
})

`trackEvent(options)`

Track a custom event with optional data.

await client.trackEvent({
  url: '/page-path',
  name: 'event_name',
  data: {
    key: 'value',
    count: 42,
    enabled: true
  },
  title: 'Page Title',
  referrer: 'https://...'
})

`track(event, eventData?)`

Flexible tracking method for backwards compatibility.

// Track with just event name
await client.track('button_click')

// Track with event name and data
await client.track('purchase', { amount: 99.99, currency: 'USD' })

// Track with full options object
await client.track({
  url: '/checkout',
  name: 'purchase_complete',
  data: { orderId: 'order_123' }
})

`identify(properties)`

Identify a user/session with custom properties.

await client.identify({
  sessionId: 'session_abc123',
  userId: 'user_456',
  plan: 'premium',
  company: 'Acme Inc'
})

Property Management

// Set a single property
client.setProperty('userId', 'user_123')

// Set multiple properties
client.setProperties({
  plan: 'enterprise',
  region: 'us-west'
})

// Get current properties
const props = client.getProperties()

// Clear a specific property
client.clearProperty('region')

// Reset all properties
client.reset()

`send(payload, type?)`

Low-level method to send raw payloads directly.

await client.send(
  {
    website: 'website-id',
    url: '/custom',
    name: 'custom_event',
    data: { custom: 'data' }
  },
  'event'
)

Advanced Usage

TypeScript Support

Full TypeScript support with exported types:

import {
  Entrolytics,
  // Error classes
  ApiError,
  ConfigurationError,
  NetworkError,
  RateLimitError,
  TimeoutError,
  ValidationError,
  EntrolyticsError,
  // Types
  type EntrolyticsOptions,
  type EntrolyticsPayload,
  type EventData,
  type TrackPageOptions,
  type TrackEventOptions,
  type IdentifyOptions,
  type SendType,
  // Phase 2 types
  type WebVitalMetric,
  type FormEventType,
  type TrackVitalOptions,
  type TrackFormEventOptions,
  type DeploymentInfo
} from '@entrolytics/node'

Type Definitions

interface EntrolyticsOptions {
  hostUrl?: string
  websiteId?: string
  sessionId?: string
  userAgent?: string
  timeout?: number
  endpoint?: 'standard' | 'edge' | 'native'
}

interface EventData {
  [key: string]: string | number | boolean | Date | null
}

interface TrackPageOptions {
  url: string
  title?: string
  referrer?: string
  hostname?: string
  language?: string
  screen?: string
}

interface TrackEventOptions extends TrackPageOptions {
  name: string
  data?: EventData
}

interface IdentifyOptions {
  sessionId?: string
  [key: string]: string | number | boolean | Date | null | undefined
}

// Phase 2 Types
type WebVitalMetric = 'LCP' | 'FID' | 'CLS' | 'FCP' | 'TTFB' | 'INP'
type WebVitalRating = 'good' | 'needs-improvement' | 'poor'
type FormEventType = 'focus' | 'blur' | 'change' | 'submit' | 'abandon'

interface TrackVitalOptions {
  metric: WebVitalMetric
  value: number
  rating: WebVitalRating
  url?: string
  navigationType?: string
}

interface TrackFormEventOptions {
  formId: string
  eventType: FormEventType
  fieldName?: string
  timeSpent?: number
  url?: string
}

interface DeploymentInfo {
  deploymentId: string
  provider?: string
  branch?: string
  commit?: string
  message?: string
}

Requirements

Node.js >= 24.20.0
Native fetch support (built into Node.js 18+)

Features

✅ CommonJS and ESM support
✅ Edge runtime compatible
✅ TypeScript-first
✅ Zero dependencies (uses native fetch)
✅ Property storage for session data
✅ Multiple endpoint support (standard/edge/native)
✅ Comprehensive error classes
✅ Web Vitals tracking (LCP, FID, CLS, FCP, TTFB, INP)
✅ Form analytics (focus, blur, submit, abandonment)
✅ Deployment tracking for CI/CD pipelines

Node.js SDK

Error Handling

Web Vitals Tracking (Phase 2)

Form Analytics (Phase 2)

Deployment Tracking (Phase 2)

Edge Endpoint

Self-Hosted Instance

Batch Tracking

On this page