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
initdoes nothing there. Call it from client-only code (a"use client"component's effect, orinstrumentation-client.tsin Next.js). -
React: errors caught by an error boundary aren't uncaught, so report them yourself from
componentDidCatch, or fromonCaughtErrorin React 19'screateRoot: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
| Option | Default | |
|---|---|---|
dsn | none | Your project's DSN. Without it, nothing is sent. |
environment | none | "production", "staging", … |
release | none | Your application's version or git sha. |
debug | false | Logs what the SDK does, prefixed [collector]. |
enabled | true | false turns everything off. |
beforeSend | none | (event) => event | null, to change or drop events. |
ignoreErrors | browser noise | Strings (matched anywhere in "Type: message") or regexps. Added to the built-in list (ResizeObserver loop…, Script error.). |
inAppUrls | same origin | Strings or regexps for script URLs that are your code. See below. |
stripQuery | true | Removes ?query and #hash from URLs. |
breadcrumbs | all on | { console, dom, fetch, xhr, history }, each true or false. |
maxBreadcrumbs | 50 | How many "what happened before" entries to keep. |
autoCapture | both on | { onerror, onunhandledrejection }, or false for neither. |
heartbeat | true | false stops the daily signal. |
rum | off | Speed 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:
sampleRateis 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 withCollector.setRoute("/orders/:id"), or passroute: (location) => …torum(). Applications that route in the#hashneed this: fragments are never sent, so every page would otherwise be/. - Changing or dropping page views:
rum({ sampleRate, beforeSendPageview(pv) { … return pv; } }); returnnullto 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/"] });
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.