Get started

Documentation

Eventra helps you track feature usage and keep analytics aligned with your codebase — runtime events via SDK, static discovery via CLI.

Runtime SDK for browser, Node, Edge, and serverless. Track events with track() — batching, retries, and delivery are handled automatically.

Install

Add the Eventra SDK to your application.

npm i @eventra_dev/eventra-sdk
pnpm add @eventra_dev/eventra-sdk
yarn add @eventra_dev/eventra-sdk

Quick start

Only apiKey is required. Events go to the production ingest endpoint by default.

import { Eventra } from "@eventra_dev/eventra-sdk";

const tracker = new Eventra({
  apiKey: "YOUR_PROJECT_API_KEY",
});

tracker.track("checkout.completed", {
  userId: "user_123",
  properties: {
    plan: "pro",
    price: 29,
  },
});

Default endpoint: https://api.eventra.dev/api/v1/ingest/batch

Event properties

Attach JSON data to any event. Validated at track() time (UTF-8 byte limits).

tracker.track("feature.used", {
  userId: "user_123",
  properties: {
    feature: "dashboard",
    plan: "pro",
  },
});

tracker.track("app.loaded");
  • Event name — max 64 characters
  • userId — max 120 characters
  • properties — max depth 8, max ~32 KB (UTF-8)
  • Batch payload — max 60 KB by default (maxPayloadBytes)

Configuration

Optional tuning for batching, retries, and error callbacks.

const tracker = new Eventra({
  apiKey: "YOUR_PROJECT_API_KEY",
  endpoint: "https://api.eventra.dev/api/v1/ingest/batch",
  flushInterval: 2000,
  maxBatchSize: 50,
  maxQueueSize: 10000,
  maxRetries: 3, // total delivery attempts per batch
  retryBaseDelayMs: 300,
  maxPayloadBytes: 60000,
  autoFlushOnExit: true, // Node / serverless
  onEventsDropped: (count) => {
    console.warn(`Dropped ${count} event(s)`);
  },
  onDeliveryFailed: ({ status, events }) => {
    console.error(`Ingest rejected (${status})`, events.length);
  },
  multiTabMode: "leader", // browser only
});
OptionDescription
apiKeyProject API key (required).
endpointIngest batch URL. Defaults to production.
flushIntervalPeriodic flush interval (ms).
maxBatchSizeMax events per outgoing batch.
maxQueueSizeMax pending events before drop.
maxRetriesTotal delivery attempts per batch (default 3).
retryBaseDelayMsBase delay for exponential backoff (ms).
maxPayloadBytesMax serialized batch size (default 60 000).
fetchImplCustom fetch (older Node, tests).
autoFlushOnExitFlush on process exit. Default true.
disableTimerDisable periodic flush timer.
onEventsDroppedCallback when the queue is full.
onDeliveryFailedPermanent ingest errors (4xx except 429).
multiTabMode"independent" (default) or "leader" (browser).

Flush & shutdown

For Node and serverless, call shutdown() before exit.

await tracker.flush();
await tracker.shutdown(); // flush + cleanup

destroy() stops timers without flushing.

Usage examples

Browser, React, Next.js, Node, NestJS, Express, Edge, and serverless.

import { Eventra } from "@eventra_dev/eventra-sdk";

const tracker = new Eventra({
  apiKey: "YOUR_PROJECT_API_KEY",
});

tracker.track("page.viewed", {
  properties: { path: window.location.pathname },
});

// optional: single sender across tabs
// multiTabMode: "leader"

Common patterns

Recipes for the four most frequent shapes of events.

// feature usage
tracker.track("feature.used", {
  userId: "user_123",
  properties: { feature: "dashboard" },
});

// page view
tracker.track("page.viewed", {
  properties: { path: window.location.pathname },
});

// API call
tracker.track("api.request", {
  properties: { endpoint: "/checkout", method: "POST", status: 200 },
});

// error
tracker.track("error.occurred", {
  properties: { message: "Payment failed", code: "PAYMENT_ERROR" },
});

Event format

This is what the SDK sends to /api/v1/ingest/batch. You never construct it by hand — the SDK handles batching, idempotency keys, and runtime detection.

{
  "sentAt": "2026-03-12T10:00:00Z",
  "sdk": {
    "name": "@eventra_dev/eventra-sdk",
    "version": "<sdk-version>",
    "runtime": "browser"
  },
  "events": [
    {
      "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
      "name": "user.signup",
      "userId": "user_123",
      "timestamp": "2026-03-12T10:00:00Z",
      "properties": {}
    }
  ]
}

Reliability

  • UUID v4 idempotency keys (safe retries across networks)
  • Property validation at track() (depth ≤ 8, ≤ 32 KB per event)
  • Exponential backoff with jitter (capped)
  • Automatic requeue on network errors and 429 / 5xx
  • Circuit breaker opens after 5 consecutive failures, cools down 5 s
  • Fetch timeout 5 s per batch
  • Dequeue only after a successful ingest response
  • Browser queue persistence + cross-tab merge
  • Leader election with automatic re-election
  • Oversized single events dropped (no poisoned queue)
  • fetch + keepalive on tab close

The examples on this page are not everything Eventra supports. The SDK and CLI work with many other frameworks and runtimes — Vue, Angular, Fastify, Hono, Cloudflare Workers, and more.

Browse runnable examples on GitHub →

Concepts