# 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](/docs/react/reference/api), [Vue](/docs/vue/reference/api), or [Svelte](/docs/svelte/reference/api).

## Exports

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

| Export | Description |
|--------|-------------|
| `flare` | Ready-to-use singleton instance. Automatically assigned to `window.flare` in the browser. |
| `Flare` | The Flare class. Use this to create additional instances, for example to report to a second project. |
| `createFlareResolver` | Builds the resolver a framework package uses internally to find the active `Flare` instance. You don't need this in application code. |

## 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](/docs/javascript/getting-started/quick-start#see-your-real-source-code), 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](/docs/javascript/reference/configuration) 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](/docs/javascript/errors/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](/docs/javascript/data-collection/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](/docs/javascript/data-collection/adding-custom-context).

### `addContextGroup(groupName, value): Flare`

Adds or replaces a named context group. See [adding custom context](/docs/javascript/data-collection/adding-custom-context).

### `setUser(user): Flare`

Attaches the current user to a report. Pass `null` to clear it. See [identifying users](/docs/javascript/data-collection/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](/docs/javascript/tracing/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](/docs/javascript/logs/introduction). 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.

```js
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](/docs/javascript/logs/introduction#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:

```js
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:

```js
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](/docs/javascript/reference/configuration#customizing-the-url-denylist) for the common case.

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

| Export | Description |
|--------|-------------|
| `DEFAULT_URL_DENYLIST` | The `RegExp` used by default to redact sensitive query-string parameter values. |
| `redactUrlQuery` | Redacts a URL's query-string values whose key matches a denylist. Used internally to build the `url.full` attribute. |
| `redactObjectValues` | The same redaction, applied to an object's values instead of a URL's query string. Not used internally by `@flareapp/js` itself, exported so you can apply the same redaction rules to your own attributes. |
| `resolveDenylist` | Combines a custom `RegExp` with the default denylist, or replaces it, the same way `flare.configure({ urlDenylist, replaceDefaultUrlDenylist })` does internally. |
| `redactUrlQuery as redactFullPath` | Deprecated alias for `redactUrlQuery`. Use `redactUrlQuery` instead. |

## Other exports

| Export | Description |
|--------|-------------|
| `Logger` | The class behind `flare.logger`. You won't normally construct this yourself. |
| `Scope`, `GlobalScopeProvider` | Building blocks for a custom `ScopeProvider`. Only relevant if you're integrating Flare into a new platform. |
| `NullFileReader` | A `FileReader` that always returns `null`, so stack frames get no source snippet. `@flareapp/js` uses a real fetch-based reader by default; pass this yourself if you want to turn snippets off. |
| `FrameworkName` | The set of framework names the Flare backend recognises, for example `FrameworkName.React`. Framework packages use this to identify themselves. |
| `toCustomContext` | Wraps a single key and value as the `context.custom` attribute, the same shape `flare.addContext()` builds. Used internally by framework packages to report their own payload as context. |
| `convertToError` | Turns a non-Error value, such as a string or a plain object, into a real `Error` instance, preserving `message`, `stack`, and `name` where present. Framework packages use this to normalize what they catch before calling `flare.report()`. |

## Exported types

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

| Type | Description |
|------|-------------|
| `Config` | The full shape of options accepted by `flare.configure()`. See the [configuration reference](/docs/javascript/reference/configuration). |
| `Attributes` | A record of attribute keys to `AttributeValue`. The shape of a report's or span's attributes. |
| `AttributeValue` | The value types an attribute can hold: string, number, boolean, `null`, or a nested array or object of those. |
| `Report` | The full shape of an error or log report, before it's sent. Used by the `beforeSubmit` hook. |
| `User` | The shape accepted by `flare.setUser()`. See [identifying users](/docs/javascript/data-collection/identifying-users). |
| `Glow` | One breadcrumb added by `flare.glow()`. |
| `MessageLevel` | The severity levels: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`. |
| `OverriddenGrouping` | The values accepted for overriding how a report is grouped. See [client hooks](/docs/javascript/errors/client-hooks). |
| `SdkInfo` | The `{ name, version }` shape reported for the SDK sending the report. |
| `Framework` | The `{ name, version? }` shape reported for the framework package in use, if any. |
| `EntryPointHandler` | Identifies the handler an error or trace happened in. Set by framework packages, not typically by application code. |
| `StackFrame` | One frame of a parsed stack trace. |
| `SpanEvent` | One event recorded on a span, for example a glow converted for a report. |
| `ContextCollector` | The function shape `Flare` calls to collect per-report attributes for a platform, for example the browser DOM or a Node request. |
| `FileReader` | The interface a platform implements to read source files for stack-trace snippets. |
| `FlushScheduler` | The interface a platform implements to drain buffers when its lifecycle ends, for example on browser unload. |
| `FlushFn` | The function shape a `FlushScheduler` calls to trigger that drain. |
| `ScopeProvider` | The interface a platform implements to hand `Flare` its current `Scope`. |