Installation

Flare's Svelte integration requires Svelte 5.3+ and uses two packages:

• @flareapp/js - the core Flare client that catches errors and sends them to Flare,
• @flareapp/svelte - the Svelte integration that provides an error boundary component and error handler.

If you're using SvelteKit, use @flareapp/sveltekit instead of @flareapp/svelte:

• @flareapp/sveltekit - the SvelteKit integration that provides error hooks for hooks.client.ts and hooks.server.ts. It includes @flareapp/svelte as a dependency and re-exports everything from it.

Optionally, you can also use the sourcemap plugin (Vite/Webpack) for resolving bundled code.

Installing the packages

For plain Svelte projects (requires Svelte 5.3+):

npm install @flareapp/js @flareapp/svelte
# or
yarn add @flareapp/js @flareapp/svelte
# or
pnpm add @flareapp/js @flareapp/svelte

For SvelteKit projects (requires SvelteKit 2.12+):

npm install @flareapp/js @flareapp/sveltekit
# or
yarn add @flareapp/js @flareapp/sveltekit
# or
pnpm add @flareapp/js @flareapp/sveltekit

Setting up the Flare client

Initialize the Flare client as early as possible in your application.

For plain Svelte, this is typically in your root component or main.ts file:

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

if (import.meta.env.PROD) {
    flare.light('YOUR PROJECT KEY');
}

For SvelteKit, initialize in src/hooks.client.ts alongside the error hook:

// src/hooks.client.ts
import { flare } from '@flareapp/js';
import { handleErrorWithFlare } from '@flareapp/sveltekit/client';

flare.light('YOUR PROJECT KEY');

export const handleError = handleErrorWithFlare();

You can find the project key on the project settings page, below the project configuration section.

If you're using the sourcemap plugin, you don't need to specify a project key here. The plugin will automatically hook up the flare.light() call to your project.

Wrapping your app in the error boundary

Wrap your component tree with FlareErrorBoundary to catch rendering errors:

<script>
    import { FlareErrorBoundary } from '@flareapp/svelte';

    let { children } = $props();
</script>

<FlareErrorBoundary>
    {@render children()}
</FlareErrorBoundary>

In SvelteKit, you can import the error boundary component from @flareapp/sveltekit. We re-export it from @flareapp/svelte.

This will catch any errors that occur during rendering and report them to Flare with Svelte-specific context like the component name, component hierarchy, and error origin.

You can learn more about the error boundary and its options in the Error boundary docs.

SvelteKit error hooks

If you're using SvelteKit, the handleErrorWithFlare() hook catches unhandled errors and reports them with SvelteKit-specific context (route, URL, params, query parameters). It also starts automatic route context tracking.

You can learn more in the SvelteKit error handling docs.

Server-side error handling (experimental)

Experimental: Server-side error handling is functional but has limited stack trace resolution since Flare we do not have sourcemap resolution for serverside code.

To catch server-side errors (in load functions, form actions, API routes), set up hooks.server.ts:

// src/hooks.server.ts
import { flare } from '@flareapp/js';
import { handleErrorWithFlare } from '@flareapp/sveltekit/server';

flare.light('YOUR PROJECT KEY');

export const handleError = handleErrorWithFlare();

Enabling the component hierarchy (optional)

By default, Flare extracts the component name from the error's stack trace. To get the full component hierarchy (from the erroring component up to the root), wrap your Svelte config with withFlareConfig in your svelte.config.js:

import { withFlareConfig } from '@flareapp/svelte/config';

export default withFlareConfig({
    // your existing config
});

withFlareConfig automatically injects the Flare preprocessor, which adds a lightweight registration call into each component at build time. This builds a parent-child chain via Svelte's context API. It's safe to call on a config that already has the preprocessor — it won't inject it twice.

To disable component tracking (e.g. in a specific environment), pass componentTracking: false:

export default withFlareConfig({
    // your existing config
}, { componentTracking: false });

You can also use flarePreprocessor() directly if you prefer manual control:

import { flarePreprocessor } from '@flareapp/svelte/config';

export default {
    preprocess: [flarePreprocessor()],
};

This is optional — everything works without it, but error reports will only include the component that threw instead of the full tree. See Component hierarchy for details on how it works and trade-offs.

Verifying your setup

The @flareapp/js client automatically assigns itself to window.flare, so you can interact with it from the browser console. To verify that Flare is correctly set up, build your app for production and run the following command in your browser console:

flare.test()

This will generate a test error that will show up on your project's dashboard in Flare.

If something goes wrong during the installation, enable debug mode by passing true as the second parameter: flare.light('key', true), or by calling flare.configure({ debug: true }).

Reporting errors, hooks and context

The Svelte integration builds on top of the core JavaScript client. For features shared with the JavaScript client, see the JavaScript docs:

• Reporting errors
• Client hooks
• Adding custom context
• Adding glows

Important notes

• If flare.light() hasn't been called (e.g. in development when using the production guard), errors are silently ignored — no reports are queued. See the JavaScript installation docs for details.
• Errors in a development environment might not always be reported. To verify the Flare client is set up correctly, test with a production build.
• For SvelteKit: the client and server hooks are separate modules (@flareapp/sveltekit/client and @flareapp/sveltekit/server). Make sure to import from the correct subpath in each hooks file.
• 4xx errors are automatically skipped by handleErrorWithFlare() since they represent expected client-side responses. To capture specific 4xx errors, use captureError() instead.