Skip to main content
This guide walks you through spinning up the Iris backend, installing the SDK in your website, and verifying that events are flowing into the dashboard.
1

Start the backend with Docker Compose

The Iris backend and dashboard are packaged as a single Docker container. Clone the repository (or copy docker-compose.yml) and run:
docker compose up -d
Docker Compose maps port 8081 on your host to port 8080 inside the container and mounts ./data for SQLite persistence. Once the container is running, the server:
  • Serves the backend API at http://localhost:8081/api
  • Serves the React dashboard at http://localhost:8081/
  • Creates and persists the SQLite database at ./data/iris.db
The docker-compose.yml sets PORT=8080, DB_PATH=/app/data/iris.db, and DASHBOARD_DIR=/app/dashboard/dist automatically. You do not need to set these manually for a default deployment.
2

Install the SDK

Add the @bigchill101/iris client package to your website project:
npm install @bigchill101/iris
The package ships ESM, CJS, and TypeScript declaration files. It has a single runtime dependency: web-vitals.
3

Initialize Iris in your app

Initialize Iris once at the root of your application — for example in _app.tsx, layout.tsx, or main.ts. Pass autocapture.pageviews: true to enable automatic pageview tracking on every navigation.
import { Iris } from '@bigchill101/iris';

const analytics = new Iris({
  // Point this to your hosted Iris backend URL
  host: "http://localhost:8081",

  // A unique identifier for this website
  siteId: "my-site",

  autocapture: {
    pageviews: true,   // track every page navigation automatically
    clicks: true,      // track clicks on buttons, links, and inputs
    webvitals: true,   // capture LCP, INP, and CLS via web-vitals
  },
});

analytics.start();
start() fires an initial $pageview event immediately, then patches history.pushState and listens to popstate so every SPA route change is tracked automatically.
The autocapture option defaults to false if omitted. You must pass an AutocaptureConfig object with the features you want enabled — or enable them individually.

​
Track custom events

Call iris.track() anywhere in your app to record custom events alongside pageviews:
analytics.track("User Signed Up", { plan: "Pro" });
analytics.track("Added to Cart", { itemId: 42, price: 99.99 });

​
Enable event batching (optional)

By default each event sends an immediate HTTP request. Enable batching to queue events and flush them together — useful for high-traffic pages:
const analytics = new Iris({
  host: "http://localhost:8081",
  siteId: "my-site",
  autocapture: {
    pageviews: true,
  },
  batching: {
    maxSize: 10,         // flush after 10 queued events (default: 10)
    flushInterval: 5000, // flush every 5 seconds (default: 5000 ms)
    flushOnLeave: true,  // flush on tab switch or close (default: true)
  },
});

analytics.start();
4

Verify it's working

Open the dashboard at http://localhost:8081/ and enter your site’s domain in the domain input field.Navigate around your website a few times, then check the dashboard for:
  • Pageviews — each navigation increments the count
  • Top pages — the URLs you visited appear in the pages table
  • Web Vitals — LCP, INP, and CLS scores appear after the browser reports them
The Iris API has no authentication. Anyone who knows your server URL can query analytics for any domain. Keep the server on a private network or behind a firewall unless you have added your own authentication layer.

​
Next steps

SDK configuration

Full reference for all IrisConfig options including batching and debug mode.

Tracking events

Learn how to track custom events and what properties are captured automatically.

Self-hosting with Docker

Environment variables, volume mounts, and production deployment considerations.

API reference

Full reference for all backend HTTP endpoints.

Build docs developers (and LLMs) love

Get started for freeTalk to us