@loomtraze/browser

Loomtraze browser SDK for production reliability telemetry.

Install

npm install @loomtraze/browser

(Workspace / monorepo: already available as @loomtraze/browser.)

Quick start

import { Loomtraze } from "@loomtraze/browser";

Loomtraze.init({
  projectKey: "lt_pk_YOUR_PROJECT_KEY",
});

That alone enables:

• Project-scoped visitor identity (lt_v_…)
• Session identity (30-minute inactivity window)
• session_started + initial page_view
• SPA page views (history.pushState / replaceState / popstate)
• PostHog-style autocapture: clicks, field changes, form submits (never input values); clicks include document-normalized coordinates for page heatmaps + rage-click flag
• session_ended on tab hide / page leave (best-effort)
• Runtime errors + unhandled rejections
• Failed fetch / XMLHttpRequest (no bodies or headers)
• Optional release_identity when release/version/build is configured
• Batched POST /v1/ingest with retries

Authenticated apps

Use an opaque internal application user id — never email, name, or phone:

// after your app knows the signed-in user
Loomtraze.identify(currentUser.id); // e.g. "user_48291"

// on logout (visitor stays the same)
Loomtraze.clearUser();

Full privacy reset (rotates visitor + session — not normal logout):

Loomtraze.resetIdentity();

Configuration

Loomtraze.init({
  projectKey: "lt_pk_...",
  // Local / staging override (default: https://api.loomtraze.com/v1/ingest)
  ingestUrl: "http://localhost:4000/v1/ingest",
  releaseId: "rel_2026_03_15",
  releaseVersion: "1.4.2",
  buildId: "build_abc",
  capture: {
    pageViews: true,
    runtimeErrors: true,
    networkFailures: true,
    interactions: true,
  },
  // Session replay is on by default. Opt out with enabled: false.
  // Clipped on error / rage / Rescue; continuous sample at 2% (not every session).
  sessionReplay: {
    sampleRate: 0.02,
  },
});

Opt out of autocapture with capture: { interactions: false }. Mark elements with data-loomtraze-ignore to skip them.

Session replay is on by default. Opt out with sessionReplay: { enabled: false }. When on, Loomtraze keeps a 2-minute masked rrweb ring buffer and uploads a clip on triggers (runtime error, network failure, rage click, Customer Rescue) or a light continuous sample rate — not every full session.

API

| Method | Purpose | | --- | --- | | Loomtraze.init(config) | Start monitoring (idempotent for same config) | | Loomtraze.identify(appUserId) | Set opaque app user for future events | | Loomtraze.clearUser() | Logout — clear app user, keep visitor | | Loomtraze.resetIdentity() | Privacy reset — new visitor + session | | Loomtraze.flush() | Send queued events now | | Loomtraze.shutdown() | Stop instrumentation (tests / HMR) | | Loomtraze.getStatus() | Non-sensitive diagnostics |

Project key

projectKey is the public lt_pk_* installation key. It is not a secret. Server admission still requires a matching production ProjectTarget origin.

Production-only by design

1. Client: Loomtraze.init() allows localhost / loopback / *.localhost by default so local feature testing works. Other private LAN origins still need allowNonProductionOrigin: true. Prefer gating production installs with enabled: process.env.NODE_ENV === "production" when you do not want local traffic.
2. Server: POST /v1/ingest only accepts events whose Origin matches an active ProjectTarget for that key. Register a localhost ProjectTarget if you want local ingest to succeed.

Privacy guarantees

The SDK never captures:

• form / input / DOM values
• cookies or non-Loomtraze storage
• request/response bodies or headers
• geolocation
• browser fingerprints
• form field values (session replay masks all inputs; passwords always masked)
• always-on full-session recording for every visitor (clips + light sample; opt out with sessionReplay.enabled: false)

Click heatmaps use only normalized page coordinates (and optional rage flags), not screenshots from the customer browser. Server-side Playwright snapshots for the Watchlist heatmap UI are a separate public-URL capture path.

Routes and endpoints are sanitized client-side (no query/fragment) before enqueueing.

AI coding-tool installation prompt

Paste into Lovable / Cursor / Claude Code:

Install @loomtraze/browser and initialize it once in the browser entry point (client-only — never in SSR/server code) with:

Loomtraze.init({
  projectKey: "lt_pk_YOUR_KEY",
  capture: {
    pageViews: true,
    interactions: true,
    runtimeErrors: true,
    networkFailures: true,
  },
});

Do not set ingestUrl (defaults to https://api.loomtraze.com/v1/ingest). Do not add server secrets, Clerk tokens, or API keys to the SDK. If the app already has authentication, after auth state is known call Loomtraze.identify with the existing opaque internal user id (never email/name/phone). On logout call Loomtraze.clearUser(). Do not call init twice, do not change unrelated code, and do not invent analytics APIs.