Getting started

Report to the console

Install the core and the console destination:

pnpm add @priemskiyyy/flare @priemskiyyy/flare-console

Create one Flare for the application, start it, and report an error:

import { Flare } from "@priemskiyyy/flare";
import { console } from "@priemskiyyy/flare-console";

export const flare = new Flare({
  destinations: { console: console() },
});

flare.start();
flare.capture(new Error("Upload failed"));
// [flare] error Error: Upload failed

Creating a Flare is cheap and starts nothing, so it is safe at module scope and on a server. start() opens the destinations. A report captured before start() is kept briefly and delivered once its destination is ready.

Say who and where

flare.user({ id: "user_42", email: "ada@example.com" });
flare.tag("plan", "pro");
flare.context("workspace", { id: "w_1", members: 12 });
flare.breadcrumb("uploadStarted", { kind: "avatar" });

flare.capture(new Error("Upload failed"), { tags: { area: "upload" } });

The user, the tag, the context and the breadcrumb describe the session, so every later report carries them. The area tag belongs to that one report only. See tags, contexts, breadcrumbs and users and account switching.

Send it to a provider

Add a destination and choose where reports go with defaults.to. This example keeps the console for development and sends reports to Sentry:

import { Flare } from "@priemskiyyy/flare";
import { console } from "@priemskiyyy/flare-console";
import { sentry } from "@priemskiyyy/flare-sentry";
import * as Sentry from "@sentry/browser";

Sentry.init({ dsn });

export const flare = new Flare({
  destinations: {
    sentry: sentry({ sdk: Sentry }),
    console: console(),
  },
  defaults: { to: ["sentry"] },
});

flare.start();

You pass the provider SDK in. Flare's adapters import no provider SDK themselves, so a browser bundle never pulls in a React Native SDK. See choose an adapter.

Know what happened

capture() is synchronous and never throws. Most code ignores what it returns. When you need to know, the receipt tells you:

const receipt = flare.capture(new Error("Upload failed"));
const status = await receipt.settled;

if (status.state === "settled" && status.outcomes.sentry?.status === "failed") {
  showOfflineBanner();
}

See receipts and evidence.

In React

import { FlareErrorBoundary, FlareProvider } from "@priemskiyyy/flare-react";

export const Root = () => (
  <FlareProvider flare={flare}>
    <FlareErrorBoundary fallback={<p>Something went wrong.</p>}>
      <Application />
    </FlareErrorBoundary>
  </FlareProvider>
);

See React and React Native and Expo. The same provider, status readers and boundary exist for Vue, Solid and Svelte.