API reference

This page covers the public surface of @flareapp/js. If you install a framework package on top of it, that package has its own API reference: see React, Vue, or Svelte.

Exports

import { flare, Flare, createFlareResolver } from '@flareapp/js';

Methods

light(key?, debug?): Flare

Initializes the Flare client with your project's public key. The key parameter defaults to the build-time constant injected by the Vite or Webpack plugin, so when using one of those plugins you can call flare.light() without arguments.

If debug is passed, it sets the debug config option.

configure(config): Flare

Merges the given options into the current configuration, so calling it a second time only changes the options you pass, and leaves the rest as they were. See the configuration reference for every available option.

report(error, attributes?): Promise<void>

Reports an error to Flare. The error parameter is typed as Error, but non-Error values, such as strings or plain objects, are automatically converted to an Error instance. The optional attributes object is merged into the report's attributes for this report only.

The beforeEvaluate and beforeSubmit client hooks both run during this call.

reportMessage(message, level?, attributes?): Promise<void>

Sends a log-style message to Flare. The level parameter is optional. If you omit it, no level is set on the report. Messages are grouped under the 'Log' exception class in the Flare dashboard.

The beforeEvaluate hook does not run for reportMessage() calls. The beforeSubmit hook still runs.

Glow methods

glow(name, level?, data?): Flare

Adds a breadcrumb. See adding glows.

• name, string: a short description of the event.
• level, MessageLevel, default 'info': the severity level.
• data, object or object[], default []: additional data to attach.

clearGlows(): Flare

Removes all collected glows.

Context methods

addContext(name, value): Flare

Adds a key-value pair to the Generic context group. See adding custom context.

addContextGroup(groupName, value): Flare

Adds or replaces a named context group. See adding custom context.

setUser(user): Flare

Attaches the current user to a report. Pass null to clear it. See identifying users.

Timing your own code

flare.startSpan() and flare.withSpan() let you time a piece of your own code as a span inside the current trace. See manual spans for how they work.

Other methods

test(): Promise<void>

Sends a real test error ("The Flare client is set up correctly!") to Flare. Use this to verify your setup.

logger: Logger

The logger instance used for structured logging. It exposes one method per severity level, debug, info, notice, warning, error, critical, alert, and emergency, each taking (message, attributes?). Logging must be enabled with the enableLogs option first.

flare.logger.info('User signed in', { userId: 42 });

flush(timeoutMs?): Promise<void>

Ships any buffered logs and spans immediately, and waits for in-flight reports to settle, up to timeoutMs (default 2000). Use this before the page does something that bypasses the automatic tab-hidden flush. See flushing manually.

createReportFromError(error, attributes?): Promise<Report | false>

Builds a full report, with stacktrace, context, and attributes, without sending it. Returns false if the error is invalid. This does not run the beforeEvaluate hook.

sendReport(report): Promise<void>

Sends a pre-built report to Flare. The beforeSubmit hook still runs, so you can use it alongside your existing hooks.

Method chaining

Most methods return the Flare instance, so you can chain calls:

flare
    .light('YOUR PROJECT KEY')
    .configure({ stage: 'production' })
    .addContext('build-id', 'abc123');

Methods that support chaining (they return the Flare instance): light(), configure(), glow(), clearGlows(), addContext(), addContextGroup(), setUser().

Methods that break the chain (they return a Promise): report(), reportMessage(), test(), flush().

Using the Flare class directly

The @flareapp/js package exports both a ready-to-use flare singleton and the Flare class itself. If you need a separate instance, for example to report to a second project, create one:

import { Flare } from '@flareapp/js';

const secondFlare = new Flare();
secondFlare.light('ANOTHER PROJECT PUBLIC KEY');

Redaction helpers

These are re-exported from @flareapp/core for building your own urlDenylist. See customizing the URL denylist for the common case.

import { DEFAULT_URL_DENYLIST, redactUrlQuery, redactObjectValues, resolveDenylist } from '@flareapp/js';

Other exports

Exported types

import type { Config, Report, User, Glow, Attributes } from '@flareapp/js';