Errors · Reference
Browser SDK
@mybeast/errors sends your pages' uncaught errors, unhandled rejections and React's own to Errors, with a trail of clicks and page changes. Plain ES modules with no dependencies, for evergreen browsers.
Install
npm install @mybeast/errorsBuild with Node 20 or later. The config comes from your server: the Laravel SDK's Errors::clientConfig() or guestConfig() (Catch browser errors).
import { init, createErrorReporter } from '@mybeast/errors';
const client = init(config); // null when the config is missing or malformed
const reporter = createErrorReporter(client, { currentPage: () => page.component });
reporter.install(); // once, before the app rendersThe config
What the Laravel SDK hands the page, and init() reads:
| Name | Type | Default | What it does |
|---|---|---|---|
url | string | - | The service's address. HTTPS, or plain HTTP on localhost, 127.0.0.1, *.localhost and *.test. |
key | string | - | The project's public key, pk_…. |
env | string | production | The environment. |
release | string | null | null | The release the page was built from. |
token | string | null | null | Signed-in pages only: who the person is, signed by your server. |
expires_at | number | - | Signed-in pages only: when the token runs out, in Unix seconds. |
token_url | string | null | null | Signed-in pages only: a path on the page's own origin that answers a fresh token. |
init
init(config, options?) returns the client, or null when anything in the config is malformed: the page then goes on as if the SDK weren't there. A token made for another project is ignored, and the page reports as a guest.
| Name | Type | Default | What it does |
|---|---|---|---|
getToken | () => Promise<string | null> | the config's token_url | A fresh token, or null once nobody is signed in. For an app that renews tokens its own way. |
The client renews its token two minutes before it runs out and when the tab comes back into view, from getToken or else the config's token_url. A failed try is tried again a minute later. After a new page's props, client.setToken(token) hands it a fresh one yourself.
createErrorReporter
createErrorReporter(client, options?) takes the client, or null, in which case nothing is sent.
| Name | Type | Default | What it does |
|---|---|---|---|
currentPage | () => string | null | none | What is on screen, such as Invoices/Show. Shown on the issue as where it broke. |
maskLabel | (label, element) => string | every label starred | Which pressed button labels may stay readable. Return the label to keep it, or star(label) to hide it. |
privateSelector | string | [data-mybeast-private] | Labels inside a matching element are always starred, whatever maskLabel says. |
onReported | ({ name, message, reference }) => void | none | Called after each report, with the reference a person can quote. |
ignore | RegExp[] | [] | Messages or stacks to drop, besides the known noise. |
maxReports | number | 10 | At most this many reports per page load. |
release | string | null | the config's | The release to send, if it isn't the one in the config. |
currentRecording | () => { id, startedAt } | null | none | The current recording of @mybeast/sessions, when the page uses both: the issue then links to the moment. |
Methods
| Method | What it does |
|---|---|
install() | Listens for uncaught errors, unhandled rejections, clicks and back and forward. Call it once, before the app renders. |
captureException(value, { kind? }) | Reports an error you caught. Returns its reference, or null when it wasn't sent: ignored, a repeat, or over the cap. |
addBreadcrumb(category, message) | Adds a step of your own to the trail sent with the next error. |
navigated(url) | Tells it about a page change your router made: pushState fires no event. Only the path is kept. |
reactRootOptions({ onUncaught? }) | Options for React 19's createRoot: reports what error boundaries caught and what they couldn't. |
lastReference() | The reference of the last report, or null. |
The package also exports star(text), which turns every letter and digit into a star, for maskLabel.
What it sends, and when
Each error goes the moment it happens, as one POST to /v1/browser-errors below the config's url. It never throws and never retries. A report holds:
- the error's name, message and stack, and React's component stack when there is one,
- what is on screen (
currentPage) and the page's path, never its query, - the last 20 breadcrumbs: clicks on buttons and links, page changes and your own, a label starred unless
maskLabelkeeps it, a link's path only, - the release and the environment, and the token, which says who it was.
The request is CORS-simple: a text/plain body, with the public key and the token in the query. It rides fetch(…, { keepalive: true }), so a report survives the page crashing or closing. Errors takes it only from an origin listed in Errors' Settings → Browser origins.
At most 10 reports go per page load, the same name and message once, and known noise (browser extensions, ResizeObserver warnings, cross-origin Script error.) is dropped.
TypeScript
The types come with the package. Every option and method above is typed:
import type { ErrorsConfig, ErrorReporterOptions, ReportedDetail } from '@mybeast/errors';