Traceway Svelte SDK

Error tracking and session replay for Svelte and SvelteKit apps. Provides setupTraceway() / getTraceway() context helpers on top of @tracewayapp/frontend.

Traceway is a completely open-source error tracking platform. You can self-host it or use Traceway Cloud.

Features

• Context-based setup that initializes Traceway exactly once during component init
• getTraceway() helper for capturing exceptions and messages from any descendant component
• Inherits everything from @tracewayapp/frontend: rrweb session replay, console logs, network/navigation actions, gzip transport
• SvelteKit's client-side routing flows through the History API and is captured automatically
• Simple one-line setup

Installation

npm install @tracewayapp/svelte

Quick Start

Call setupTraceway in your root component:

<script>
  import { setupTraceway } from "@tracewayapp/svelte";

  setupTraceway({
    connectionString: "your-token@https://traceway.example.com/api/report",
  });
</script>

<slot />

That's it. setupTraceway runs init(...) synchronously, which installs window.onerror, unhandledrejection, the console.* mirror, the fetch / XHR instrumentation, the History API instrumentation, and the rrweb recorder.

Render-time errors

Svelte does not have a global error-boundary primitive like React or Vue. The global window.onerror and unhandledrejection handlers catch runtime errors (event handlers, async work, network failures), but a component that throws during render does not automatically reach those handlers.

• Svelte 5+ ships <svelte:boundary>. Pipe its onerror prop into Traceway via the exported captureSvelteError helper:

  <script>
    import { captureSvelteError } from "@tracewayapp/svelte";
  </script>
  
  <svelte:boundary onerror={(error) => captureSvelteError(error)}>
    <YourApp />
    {#snippet failed(error, reset)}
      <p>Something went wrong.</p>
    {/snippet}
  </svelte:boundary>

• Svelte 4 has no boundary primitive at all. Wrap risky code in try/catch and call captureSvelteError(err) manually, or upgrade to Svelte 5 for <svelte:boundary>.

SvelteKit

In SvelteKit, set up Traceway in the root layout — and gate it on the browser import so it doesn't run during SSR:

<!-- src/routes/+layout.svelte -->
<script>
  import { setupTraceway } from "@tracewayapp/svelte";
  import { browser } from "$app/environment";

  if (browser) {
    setupTraceway({
      connectionString: "your-token@https://traceway.example.com/api/report",
    });
  }
</script>

<slot />

Manual Capture

Use getTraceway in child components:

<script>
  import { getTraceway } from "@tracewayapp/svelte";

  const { captureException } = getTraceway();

  async function handleSubmit() {
    try {
      await submitForm();
    } catch (error) {
      captureException(error);
    }
  }
</script>

<button on:click={handleSubmit}>Submit</button>

To record a custom action breadcrumb, import recordAction directly from @tracewayapp/frontend (it's not on the context surface):

import { recordAction } from "@tracewayapp/frontend";

recordAction("checkout", "payment_submitted", { amount: 42 });

Custom Attributes (global scope)

Two ways to attach app-level identifiers (userId, tenant, feature flags, …) to every session and exception.

Declarative — useTracewayAttributes, a factory that returns a sync function. Call once during component setup; invoke the returned function from $effect (Svelte 5) or $: (Svelte 4). The hook diffs the new map against the previous one and pushes only the deltas; on onDestroy every key it currently owns is removed.

<!-- Svelte 5 -->
<script>
  import { useTracewayAttributes } from "@tracewayapp/svelte";
  let { user, org } = $props();
  const sync = useTracewayAttributes();
  $effect(() => sync({ userId: user.id, tenant: org.id }));
</script>

<!-- Svelte 4 -->
<script>
  import { useTracewayAttributes } from "@tracewayapp/svelte";
  export let user; export let org;
  const sync = useTracewayAttributes();
  $: sync({ userId: user.id, tenant: org.id });
</script>

The sync function accepts null / undefined as "empty map" — useful while user data loads or after logout. The factory must run during component init so onDestroy can register cleanup.

Imperative — setAttribute / setAttributes / removeAttribute / clearAttributes. Use these outside component trees (+layout.ts load functions, server hooks that run client-side after hydration):

import {
  setAttribute,
  setAttributes,
  clearAttributes,
} from "@tracewayapp/svelte";

setAttribute("build_channel", "canary");
setAttributes({ tenant: "acme", plan: "pro" });
// ...later, on logout:
clearAttributes();

Layering order on each event: auto-collected defaults < global scope < per-call attributes. See the @tracewayapp/frontend README for the full mechanics.

Always-on Session Recording

Pass recordAllSessions: true to upload full sessions continuously (not just exception-bound clips):

<script>
  setupTraceway({
    connectionString: "your-token@https://traceway.example.com/api/report",
    options: { recordAllSessions: true },
  });
</script>

See the @tracewayapp/frontend README for the full description.

Options

The options field forwards directly to @tracewayapp/frontend. The most-used flags:

| Option | Default | Description | |--------|---------|-------------| | version | "" | App version string, attached to every report | | debug | false | Print debug info to the console | | captureLogs | true | Mirror console.* into the rolling log buffer | | captureNetwork | true | Record fetch / XHR as network actions | | captureNavigation | true | Record History API push / replace / pop as navigation actions | | sessionRecording | true | Enable the rrweb session recorder | | recordAllSessions | false | Always-on session recording (every ~30 s segment uploaded continuously) | | eventsWindowMs | 10000 | Rolling window kept in the log/action buffers (ms) | | eventsMaxCount | 200 | Hard cap applied independently to logs and actions |

See the @tracewayapp/frontend README for the full options reference.

Logs & Actions

Each captured exception ships with the buffered logs, actions, and replay frames:

• Logs — console.{debug, log, info, warn, error} mirrored into a rolling buffer.
• Actions — fetch / XHR and History API navigations recorded as breadcrumbs. SvelteKit's client-side routing is captured automatically.
• Session recordings — rrweb-based replay of the seconds leading up to each exception.

API

setupTraceway(config)

Initializes Traceway and stores the API in Svelte context. Must be called during component initialization.

| Field | Type | Description | |-------|------|-------------| | connectionString | string | Traceway connection string (token@url) | | options | TracewayFrontendOptions | Forwarded to init() from @tracewayapp/frontend |

Returns { captureException, captureExceptionWithAttributes, captureMessage }.

getTraceway()

Returns { captureException, captureExceptionWithAttributes, captureMessage }.

Throws if used outside a component tree where setupTraceway has been called.

useTracewayAttributes()

Returns a (attrs: Record<string, string> | null | undefined) => void setter. Call once during component init, then invoke the setter from $effect (Svelte 5) or a $: reactive statement (Svelte 4). Diffs against the last map; removes every owned key on onDestroy.

Platform Support

| Environment | Error Tracking | Session Replay | |---|---|---| | Svelte 4+ in any modern browser | Yes | Yes | | SvelteKit (browser) | Yes | Yes | | SvelteKit SSR | Skip — gate on $app/environment.browser | No |

Links

• Traceway Website
• Traceway GitHub
• Documentation
• Browser SDK

License

MIT