# API reference


The Svelte integration builds on top of the core JavaScript client. For the base API reference (method chaining, configuration, using the Flare class directly), see the [JavaScript API reference](/docs/javascript/reference/api).

`@flareapp/svelte` ships three entry points: the package root, `/config`, and `/inject`.

## `@flareapp/svelte`

```ts
import { FlareErrorBoundary, createFlareErrorHandler, withFlareConfig, flarePreprocessor } from '@flareapp/svelte';
```

| Export | Description |
|--------|-------------|
| `FlareErrorBoundary` | Svelte error boundary component that wraps `<svelte:boundary>` to catch rendering errors and report them to Flare. See [Error boundary](/docs/svelte/errors/error-boundary). |
| `createFlareErrorHandler` | Factory function that returns an `onerror` callback for use with Svelte's native `<svelte:boundary>`. See [Error handler](/docs/svelte/errors/error-handler). |
| `withFlareConfig` | Wraps your `svelte.config.js` export to inject the Flare preprocessor for component tracking and component profiling. Also re-exported from `/config`; see below. |
| `flarePreprocessor` | Svelte preprocessor that injects component registration and profiling calls. Use this for manual preprocessor setup instead of `withFlareConfig`. Also re-exported from `/config`. |

Importing from the root also registers `@flareapp/svelte`'s identity on the default `flare` instance from `@flareapp/js`, so reports are tagged as coming from Svelte. If you don't want that, for example outside a normal web page, use `/inject` instead.

### TypeScript

```ts
import type {
    FlareSvelteContext,
    SvelteErrorOrigin,
    FlarePreprocessorOptions,
    WithFlareConfigOptions,
} from '@flareapp/svelte';
```

| Type | Description |
|------|-------------|
| `FlareSvelteContext` | Shape of the `context` argument passed to `beforeSubmit` / `afterSubmit`: `{ svelte: { componentName, componentHierarchy, errorOrigin } }`. |
| `SvelteErrorOrigin` | Normalized error origin category: `"render" \| "event" \| "effect" \| "unknown"`. |
| `FlarePreprocessorOptions` | Options accepted by `flarePreprocessor()` (`exclude`, `importSource`, `componentTracking`, `profileComponents`, `routesDir`). |
| `WithFlareConfigOptions` | Options accepted by `withFlareConfig()` (`componentTracking`, `profileComponents`, `exclude`, `importSource`). |

## `@flareapp/svelte/config`

`withFlareConfig` and `flarePreprocessor` are also exported from this separate subpath, so they can be imported in `svelte.config.js` (which runs in Node.js) without pulling in Svelte's runtime code:

```js
import { withFlareConfig, flarePreprocessor } from '@flareapp/svelte/config';
```

### `WithFlareConfigOptions`

Options passed as the second argument to `withFlareConfig(config, options)`:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `componentTracking` | `boolean` | `true` | Injects the component tree registration used to build the full component hierarchy on an error report. See [Component hierarchy](/docs/svelte/errors/error-boundary#component-hierarchy). |
| `profileComponents` | `boolean \| (string \| RegExp)[]` | `false` | Records a `browser_component` span per matched component mount. Matched against the [route aware profile name](/docs/svelte/profiling/introduction#which-name-to-match), not the bare component name. An empty array is treated the same as `false`. `true` profiles every component, a debugging aid, not something to ship. Requires `enableTracing`. See [profiling introduction](/docs/svelte/profiling/introduction). |
| `exclude` | `RegExp` | - | Files matching this pattern are skipped entirely: no component tracking and no profiling. |
| `importSource` | `string` | `'@flareapp/svelte'` | Where the preprocessor's injected code imports `__flareRegisterComponent` and `__flareProfileComponent` from. Set this to `'@flareapp/svelte/inject'` when using the injected build (see `/inject` below). |

`withFlareConfig` is a no-op, and returns your config unchanged, when both `componentTracking` is `false` and `profileComponents` resolves to nothing (`false` or an empty array). It also skips re-injecting the preprocessor if a Flare preprocessor is already installed.

## SvelteKit exports (`@flareapp/sveltekit`)

The `@flareapp/sveltekit` package re-exports everything from `@flareapp/svelte` (`export * from '@flareapp/svelte'`) and adds SvelteKit-specific hooks via subpath exports.

### Client (`@flareapp/sveltekit/client`)

```ts
import {
    handleErrorWithFlare,
    captureError,
    trackRouteContext,
    traceSvelteKitRouter,
} from '@flareapp/sveltekit/client';
```

| Export | Description |
|--------|-------------|
| `handleErrorWithFlare` | Factory function that returns a SvelteKit-compatible `handleError` hook for `hooks.client.ts`. Automatically skips 4xx errors and starts route tracking. See [SvelteKit error handling](/docs/svelte/errors/sveltekit-error-handling). |
| `captureError` | Manually report an error to Flare with SvelteKit route context. Does not skip 4xx errors. See [Capturing errors](/docs/svelte/errors/sveltekit-error-handling#capturing-errors-manually). |
| `trackRouteContext` | Starts reactive route tracking, syncing the current route to Flare's context on every navigation. Also started as a side effect of importing `handleErrorWithFlare` from this subpath. Calling it more than once has no effect. |
| `traceSvelteKitRouter` | Traces SvelteKit's client router: `() => () => void`. Takes no arguments, unlike a router integration in other frameworks; it reads SvelteKit's own navigation state through `$app/state` instead. Names `browser_navigation` and `browser_pageload` spans after the matched route. Returns a stop function. See [tracing introduction](/docs/svelte/tracing/introduction). |

### Server (`@flareapp/sveltekit/server`)

> **Experimental:** Server-side error handling is functional but has limited stack trace resolution.

```ts
import {
    handleErrorWithFlare,
    captureError,
} from '@flareapp/sveltekit/server';
```

| Export | Description |
|--------|-------------|
| `handleErrorWithFlare` | Factory function that returns a SvelteKit-compatible `handleError` hook for `hooks.server.ts`. Automatically skips 4xx errors. See [SvelteKit error handling](/docs/svelte/errors/sveltekit-error-handling). |
| `captureError` | Manually report a server-side error to Flare with route context from a `RequestEvent`. See [Capturing errors](/docs/svelte/errors/sveltekit-error-handling#capturing-errors-manually). |

## `@flareapp/svelte/inject`

```ts
import { FlareErrorBoundary, createFlareErrorHandler, withFlareConfig, flarePreprocessor } from '@flareapp/svelte/inject';
```

Exports the same `FlareErrorBoundary`, `createFlareErrorHandler`, `withFlareConfig`, and `flarePreprocessor` as the root package, with the same TypeScript types. The difference is what happens on import: `/inject` has no side effects and doesn't register a default `flare` instance or a Svelte identity tag. Every call needs an explicit `flare` option (on `createFlareErrorHandler`) or `flare` prop (on `FlareErrorBoundary`) instead of falling back to a default. Use this when you're embedding Flare's Svelte integration somewhere that isn't a normal web page, for example a renderer process that already manages its own `Flare` instance. When using `/inject`, also set the preprocessor's `importSource` option to `'@flareapp/svelte/inject'`.

## TypeScript (`@flareapp/sveltekit`)

The `@flareapp/sveltekit` package root re-exports every type from `@flareapp/svelte` and nothing else (`packages/sveltekit/src/index.ts` is just `export * from '@flareapp/svelte'`). Its own two extra types are exported from the `/client` and `/server` subpaths instead:

```ts
import type { HandleErrorWithFlareOptions, CaptureErrorOptions } from '@flareapp/sveltekit/client';
```

The same two types are exported from `@flareapp/sveltekit/server` as well.

| Type | Description |
|------|-------------|
| `HandleErrorWithFlareOptions` | Options accepted by `handleErrorWithFlare()` (`beforeEvaluate`, `beforeSubmit`, `afterSubmit`). The `context` passed to `beforeSubmit`/`afterSubmit` has the shape described by `FlareSvelteKitContext` below. |
| `CaptureErrorOptions` | Options accepted by `captureError()` (`event`, `status`, `message`). |
| `FlareSvelteKitContext` | Not exported from any entry point; documented here because it's the shape of `HandleErrorWithFlareOptions`'s `context`. Extends `FlareSvelteContext` with SvelteKit route data: `{ svelte: { ..., svelteKit?: { routeId, url, params, query, status?, message? } } }`. |
| `SvelteKitRouteContext` | Not exported from any entry point; documented here because it's embedded in `FlareSvelteKitContext`. Route information: `routeId`, `url` (pathname), `params`, `query` (redacted), and optional `status`/`message`. |