Context Setup

Understanding Traceway's Svelte context integration.

How It Works

Traceway uses Svelte's context API to provide error capture functions to your component tree:

setupTraceway() initializes the SDK and sets context
getTraceway() retrieves the context in child components

setupTraceway

Must be called during component initialization (not in an event handler):

<script>
  import { setupTraceway } from "@tracewayapp/svelte";
 
  // Correct: called at component initialization
  setupTraceway({
    connectionString: "your-token@https://traceway.example.com/api/report",
  });
</script>

Delayed Initialization: The SDK initialization (init()) is deferred until onMount. This means the actual connection to the Traceway server happens after the component mounts, not during the initial script execution. The context functions (captureException, etc.) are available immediately, but events captured before mount will be queued and sent once initialization completes.

Options

Option	Type	Required	Description
`connectionString`	`string`	Yes	Your Traceway connection string
`options`	`object`	No	SDK configuration

SDK Options

Option	Type	Default	Description
`debug`	`boolean`	`false`	Log events to console
`debounceMs`	`number`	`1500`	Batch delay in milliseconds
`retryDelayMs`	`number`	`10000`	Retry delay for failed uploads
`version`	`string`	`undefined`	Your application version
`ignoreErrors`	`Array<string \| RegExp>`	`DEFAULT_IGNORE_PATTERNS`	Error patterns to ignore. Pass `[]` to capture all errors. See Error Filtering
`beforeCapture`	`(exception) => boolean`	`undefined`	Return `false` to suppress an error. See Error Filtering
`sessionRecording`	`boolean`	`true`	Enable the rrweb session recorder
`sessionRecordingSegmentDuration`	`number`	`30000`	rrweb segment length in ms
`recordAllSessions`	`boolean`	`false`	Always-on session recording. See Sessions
`captureLogs`	`boolean`	`true`	Mirror `console.*` calls into the rolling log buffer
`captureNetwork`	`boolean`	`true`	Record `fetch` / `XHR` calls as network actions
`captureNavigation`	`boolean`	`true`	Record History API push / replace / pop transitions

getTraceway

Retrieve capture functions in any child component:

<script>
  import { getTraceway } from "@tracewayapp/svelte";
 
  const { captureException, captureExceptionWithAttributes, captureMessage } = getTraceway();
</script>

Return Value

Function	Description
`captureException(error)`	Capture an error with stack trace
`captureExceptionWithAttributes(error, attributes)`	Capture error with metadata
`captureMessage(message)`	Send a custom message

Complete Example

Root layout:

<!-- src/routes/+layout.svelte -->
<script>
  import { setupTraceway } from "@tracewayapp/svelte";
  import { browser } from "$app/environment";
  import { PUBLIC_TRACEWAY_CONNECTION } from "$env/static/public";
 
  if (browser) {
    setupTraceway({
      connectionString: PUBLIC_TRACEWAY_CONNECTION,
      options: {
        debug: import.meta.env.DEV,
      },
    });
  }
</script>
 
<slot />

Child component:

<!-- src/lib/components/Form.svelte -->
<script>
  import { getTraceway } from "@tracewayapp/svelte";
 
  const { captureException, captureExceptionWithAttributes } = getTraceway();
 
  let formData = { email: "", name: "" };
 
  async function handleSubmit() {
    try {
      const response = await fetch("/api/submit", {
        method: "POST",
        body: JSON.stringify(formData),
      });
      if (!response.ok) throw new Error("Submission failed");
    } catch (error) {
      captureExceptionWithAttributes(error, {
        email: formData.email,
        action: "form_submit",
      });
    }
  }
</script>
 
<form on:submit|preventDefault={handleSubmit}>
  <input bind:value={formData.name} placeholder="Name" />
  <input bind:value={formData.email} placeholder="Email" />
  <button type="submit">Submit</button>
</form>

Custom Attributes

Use useTracewayAttributes to bind a reactive map of attributes (userId, tenant, feature flags, etc.) to the SDK's global scope. It's a factory: call it once during component setup, then invoke the returned setter from $effect (Svelte 5) or $: (Svelte 4). The setter diffs against the last map and pushes only the deltas; onDestroy removes every key it currently owns.

<!-- 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 setter accepts null / undefined as "empty map" — useful while user data loads or after logout.

For imperative use (load functions, hooks), the same primitives are exported as plain functions:

import { setAttribute, setAttributes, removeAttribute, clearAttributes } from "@tracewayapp/svelte";
 
setAttribute("build_channel", "canary");
setAttributes({ tenant: "acme", plan: "pro" });
clearAttributes(); // on logout

Layering on each event: defaults < global scope < per-call. See Sessions for the full attribute model.

TRACEWAY_KEY

For advanced use cases, you can access the context key directly:

<script>
  import { getContext } from "svelte";
  import { TRACEWAY_KEY } from "@tracewayapp/svelte";
 
  const traceway = getContext(TRACEWAY_KEY);
</script>

SvelteKit Error Handling

For SvelteKit's error handling, create a custom error hook:

// src/hooks.client.js
import { getTraceway } from "@tracewayapp/svelte";
 
export function handleError({ error, event }) {
  // Note: Context may not be available in hooks
  // Consider using the core SDK directly here
  console.error("Unhandled error:", error);
}

For client-side errors, use +error.svelte:

<!-- src/routes/+error.svelte -->
<script>
  import { page } from "$app/stores";
  import { getTraceway } from "@tracewayapp/svelte";
  import { onMount } from "svelte";
 
  const { captureException } = getTraceway();
 
  onMount(() => {
    if ($page.error) {
      captureException($page.error);
    }
  });
</script>
 
<h1>Error: {$page.status}</h1>
<p>{$page.error?.message}</p>

Environment Variables

For SvelteKit, use public environment variables:

# .env
PUBLIC_TRACEWAY_CONNECTION=your-token@https://traceway.example.com/api/report

<script>
  import { PUBLIC_TRACEWAY_CONNECTION } from "$env/static/public";
 
  setupTraceway({
    connectionString: PUBLIC_TRACEWAY_CONNECTION,
  });
</script>

Best Practices

Initialize early: Call setupTraceway in your root layout
Check for browser: In SvelteKit, only initialize on the client
Use attributes: Add context with captureExceptionWithAttributes
Handle gracefully: Show user-friendly errors while capturing details

<script>
  import { getTraceway } from "@tracewayapp/svelte";
 
  const { captureException } = getTraceway();
  let error = null;
 
  async function loadData() {
    try {
      const data = await fetchData();
      // use data
    } catch (e) {
      captureException(e);
      error = "Failed to load data. Please try again.";
    }
  }
</script>
 
{#if error}
  <p class="error">{error}</p>
{/if}

Quick Start Quick Start