Skip to main content

Browser

The @chrom-ar/collector package reports your browser application's errors. It works with any framework (React, Vue, Svelte, Angular, plain pages), has no dependencies and weighs about 6 KB gzipped. This page describes version 0.4.0.

Installation​

npm install @chrom-ar/collector

As early as possible in your application's entry point (main.ts, index.js, …), before it renders:

import * as Collector from "@chrom-ar/collector";

Collector.init({
dsn: "https://clt_…@app.clt.chrom.ar", // from your project's setup page
environment: "production",
release: "web@1.4.2",
});

That's it. From now on, uncaught errors and unhandled promise rejections are reported on their own, along with what happened right before them: clicks, navigation, network requests and console messages.

The DSN is public: it can only send events, so it's fine in browser code. Without a DSN nothing is captured or sent, so dev and tests stay quiet when you leave it out:

Collector.init({ dsn: import.meta.env.VITE_COLLECTOR_DSN });

environment and release are optional. Issues are counted per environment, and release tells you which deploy an error came from.

New domains​

The first time events arrive from a new domain, Collector keeps them and asks the project's admins whether that domain is theirs. If they block it, pages there stop sending, and a [collector] notice saying the domain is blocked shows once in the browser console. See Allowed domains.

Content Security Policy​

If your site sends a Content Security Policy, add your DSN's origin (scheme, host and port) to connect-src, next to the ones you already allow:

Content-Security-Policy: connect-src 'self' https://app.clt.chrom.ar

Nothing else is needed, with or without speed measuring: everything goes out with fetch or navigator.sendBeacon, which connect-src covers, and nothing is needed in script-src, since the package is bundled with your code and loads no scripts or uses eval. If connect-src is missing it, the browser blocks the requests and nothing reaches Collector; Collector.test() says so.

Framework notes​

  • Next.js, Nuxt, SvelteKit and other server-rendering frameworks: importing the package on the server is safe, and init does nothing there. Call it from client-only code (a "use client" component's effect, or instrumentation-client.ts in Next.js).

  • React: errors caught by an error boundary aren't uncaught, so report them yourself from componentDidCatch, or from onCaughtError in React 19's createRoot:

    createRoot(el, { onCaughtError: (error) => Collector.captureException(error) });
  • Vue: add app.config.errorHandler = (error) => Collector.captureException(error);

Checking it works​

const result = await Collector.test();
// { ok: true, id: "…" } or { ok: false, reason: "Collector rejected the key (HTTP 401)…" }

It also logs one line to the console. The event is a CollectorTest error tagged collector.test: "true", and every test groups into one issue. With debug: true, it's also on window.__collector.test(), so you can run it from the console without importing anything.

Reporting by hand​

try {
await checkout(cart);
} catch (error) {
Collector.captureException(error, { tags: { step: "payment" } });
showRetry();
}

Collector.captureMessage("Payment gateway slow", "warning");

Both return the event's id, or undefined when nothing was sent.

Users and tags​

Say who hit the error, by id (not personal data), and add tags to filter by:

Collector.setUser({ id: currentUser.id });
Collector.setTag("plan", "pro");

setUser(null) clears the user on logout. There are also setTags(tags), addBreadcrumb({ message, category?, level? }), flush(timeoutMs?) (waits until queued events are sent) and close() (removes everything the SDK installed).

Privacy​

What the SDK sends and leaves out is in Security and privacy. beforeSend sees every event last, and can change it or drop it:

Collector.init({
dsn: "…",
beforeSend(event) {
if (event.request) event.request.url = event.request.url.replace(/\/users\/\d+/, "/users/:id");
return event; // or null to drop it
},
});

Options​

OptionDefault
dsnnoneYour project's DSN. Without it, nothing is sent.
environmentnone"production", "staging", …
releasenoneYour application's version or git sha.
debugfalseLogs what the SDK does, prefixed [collector].
enabledtruefalse turns everything off.
beforeSendnone(event) => event | null, to change or drop events.
ignoreErrorsbrowser noiseStrings (matched anywhere in "Type: message") or regexps. Added to the built-in list (ResizeObserver loop…, Script error.).
inAppUrlssame originStrings or regexps for script URLs that are your code. See below.
stripQuerytrueRemoves ?query and #hash from URLs.
breadcrumbsall on{ console, dom, fetch, xhr, history }, each true or false.
maxBreadcrumbs50How many "what happened before" entries to keep.
autoCaptureboth on{ onerror, onunhandledrejection }, or false for neither.
heartbeattruefalse stops the daily signal.
rumoffSpeed measuring. See below.

Page speed​

Speed measuring shows how fast your pages are for the people using them: Web Vitals per page, the slow requests and the single visits, in the Speed tab. It's off by default and ships as a separate import, so applications that don't use it don't download it (about 4.5 KB gzipped):

import * as Collector from "@chrom-ar/collector";
import { rum } from "@chrom-ar/collector/rum";

Collector.init({ dsn: "…", rum: rum({ sampleRate: 0.1 }) });
  • Sampling: sampleRate is the share of browser tabs measured, decided once per tab. A measured tab sends all its page views.
  • What's measured: for page loads, LCP, INP, CLS, TTFB and FCP; for in-app navigations to a new path (pushState, LiveView), INP, CLS and a navigation time, from the click until the page's requests have finished and the DOM has been quiet for half a second (at most 10 s). A query string change alone, like a filter, stays the same page view. Plus the page's fetch and XHR calls, and for slow pages the slowest resources it loaded.
  • When it sends: in batches, when the tab is hidden or closed, and every 10 page views or 5 minutes while it stays open. If Collector is down or slow, they're dropped without retrying.
  • Privacy: no cookies, no user, no query strings or fragments. A random id for the visit and the sampling decision are kept in sessionStorage (collector:rum) and end with the tab. Errors from a measured tab carry the visit's id, so an issue links to its visit. Whether you need consent for analytics is your call.
  • Routes: Collector groups pages by guessing which path segments are ids (/orders/81 → /orders/:id). If your router knows the route, say it after each navigation with Collector.setRoute("/orders/:id"), or pass route: (location) => … to rum(). Applications that route in the #hash need this: fragments are never sent, so every page would otherwise be /.
  • Changing or dropping page views: rum({ sampleRate, beforeSendPageview(pv) { … return pv; } }); return null to drop one.

What counts as your code​

The SDK marks a stack frame as your code when its script is on the page's own origin (or is a webpack dev module) and isn't a dependency bundle (node_modules, .vite/deps, vendor chunks, Next.js framework chunks). Content hashes in file names are ignored, so a new deploy doesn't open new issues. If your scripts come from a CDN, say so:

Collector.init({ dsn: "…", inAppUrls: ["https://cdn.example.com/app/"] });

See How events are grouped.

Source maps​

Upload each build's maps and Collector shows your original files, lines and functions, and groups by them. See Source maps.

How it behaves​

It never throws into your application, never blocks it and stays quiet in the console unless something's misconfigured (or you set debug: true). When an error repeats in a loop, it sends it once; and it sends at most 30 events every 10 seconds per page.

Safari sometimes leaves frames out, so the same error can occasionally group separately in that browser. For servers, use Node or Elixir.