Skip to main content

​
IrisConfig

The configuration object passed to new Iris(config).
​
host
string
required
The base URL of your self-hosted Iris backend server. No trailing slash.
host: 'https://analytics.yourdomain.com'
​
siteId
string
required
A unique identifier for this website or project. Used to logically group events from the same site. Stored in every event payload as the s field.
siteId: 'my-awesome-app'
​
autocapture
AutocaptureConfig | false
default:"false"
Controls which events are tracked automatically. Pass false (default) to disable all autocapture, or pass an AutocaptureConfig object to enable specific features.
// Enable all automatic tracking
autocapture: { pageviews: true, clicks: true, webvitals: true }

// Enable only pageview tracking
autocapture: { pageviews: true }

// Disable all autocapture (default)
autocapture: false
​
debug
boolean
default:"false"
Enables verbose console logging. When true, Iris logs each event as it is sent or queued, and logs errors from failed network requests.
​
batching
BatchConfig
Optional batching configuration. When omitted, every event fires an immediate HTTP request. See Event Batching for details.

​
AutocaptureConfig

​
autocapture.pageviews
boolean
default:"false"
When true, fires a $pageview event on start(), patches history.pushState for SPA navigation, and listens to popstate for back/forward navigation.
​
autocapture.clicks
boolean
default:"false"
When true, attaches a global click listener that automatically records $click events on button, a, input[type="submit"], and [role="button"] elements. Elements with the .iris-ignore CSS class are skipped. input[type="password"] is always excluded.
​
autocapture.webvitals
boolean
default:"false"
When true, hooks into the web-vitals library to automatically send $web_vital events for LCP, INP, and CLS.

​
BatchConfig

​
batching.maxSize
number
default:"10"
The number of events to queue before triggering a flush. When the queue reaches this size, all queued events are sent immediately in a single POST /api/events request.
​
batching.flushInterval
number
default:"5000"
The interval in milliseconds between automatic flushes. A setInterval timer runs at this cadence and sends any queued events.
​
batching.flushOnLeave
boolean
default:"true"
When true, queued events are flushed when the user switches tabs (visibilitychange) or navigates away (pagehide). Uses navigator.sendBeacon for reliable delivery on page unload.

​
Full example

import { Iris } from '@bigchill101/iris';

const analytics = new Iris({
  host: 'https://analytics.yourdomain.com',
  siteId: 'my-site',
  autocapture: {
    pageviews: true,
    clicks: true,
    webvitals: true,
  },
  debug: false,
  batching: {
    maxSize: 10,
    flushInterval: 5000,
    flushOnLeave: true,
  },
});

analytics.start();

Build docs developers (and LLMs) love

Get started for freeTalk to us