Svelte SDK

@traffical/svelte integrates Traffical with Svelte’s runes and SvelteKit’s data-loading system. It wraps @traffical/js-client, so everything the browser client supports works here too. Requires Svelte 5 (uses runes).

Installation

npm install @traffical/svelte

pnpm add @traffical/svelte

yarn add @traffical/svelte

Setup

Wrap your app with TrafficalProvider in a root layout:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import { TrafficalProvider } from "@traffical/svelte";

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

<TrafficalProvider config={{
  orgId: "org_acme",
  projectId: "proj_marketplace",
  env: "production",
  apiKey: import.meta.env.PUBLIC_TRAFFICAL_API_KEY,
}}>
  {@render children()}
</TrafficalProvider>

Use an SDK key (traffical_sk_..., scopes sdk:read+sdk:write) in browser code — it is browser-safe.

Resolving parameters

Use useTraffical in any component:

<script lang="ts">
  import { useTraffical } from "@traffical/svelte";

  const { params, track } = useTraffical({
    defaults: {
      "checkout.button.color": "#1E6EFB",
      "checkout.button.label": "Buy now",
    },
  });
</script>

<button
  style:background-color={params["checkout.button.color"]}
  onclick={() => track("cta_click")}
>
  {params["checkout.button.label"]}
</button>

params is reactive via runes — Svelte automatically re-renders when the bundle refreshes or context changes.

Setting context

TrafficalProvider takes exactly two props: config and children. Context is supplied through config.contextFn — a function called on each resolution, so hooks re-resolve when the values it returns change:

<script lang="ts">
  import { TrafficalProvider } from "@traffical/svelte";
  import { page } from "$app/state";

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

<TrafficalProvider
  config={{
    orgId: "org_acme",
    projectId: "proj_marketplace",
    env: "production",
    apiKey: import.meta.env.PUBLIC_TRAFFICAL_API_KEY,
    contextFn: () => ({
      userId: page.data.user?.id ?? "anonymous",
      locale: navigator.language,
    }),
  }}
>
  {@render children()}
</TrafficalProvider>

To customize the unit key, pass unitKeyFn inside config as well.

SvelteKit SSR

Fetch the bundle in a server load function and pass it through to the client to avoid a second fetch:

// src/routes/+layout.server.ts
import { loadTrafficalBundle } from "@traffical/svelte/sveltekit";
import { TRAFFICAL_API_KEY } from "$env/static/private";

export async function load({ fetch }) {
  const { bundle } = await loadTrafficalBundle({
    orgId: "org_acme",
    projectId: "proj_marketplace",
    env: "production",
    apiKey: TRAFFICAL_API_KEY,
    fetch,    // SvelteKit's fetch for proper caching
  });

  return { traffical: { bundle } };
}

<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import { TrafficalProvider } from "@traffical/svelte";
  let { data, children } = $props();
</script>

<TrafficalProvider
  config={{
    orgId: "org_acme",
    projectId: "proj_marketplace",
    env: "production",
    apiKey: import.meta.env.PUBLIC_TRAFFICAL_API_KEY,
    initialBundle: data.traffical.bundle,
  }}
>
  {@render children()}
</TrafficalProvider>

The server resolves with the bundle. The client picks up the same bundle via initialBundle and hydrates without a second fetch. No flash of original content.

The server-fetched bundle goes through initialBundle — that is what marks the provider ready during SSR. localConfig is the separate build-time/offline fallback bundle. Without an initialBundle (client-only usage), params start at your defaults and update as soon as the first background fetch lands.

See SSR patterns for the full pattern, including per-page pre-resolution.

Anonymous users and `identify`

The Svelte SDK uses the browser client’s stable-ID handling. When the user logs in: useTrafficalClient() returns { client, ready, error } — destructure client (it can be null until the provider initializes):

<script lang="ts">
  import { useTrafficalClient } from "@traffical/svelte";

  const { client } = useTrafficalClient();

  function login(user) {
    client?.identify(user.id);
  }
</script>

Overview

Server SDKs

Client SDKs

Integrations

Patterns

Installation

Setup

Resolving parameters

Setting context

SvelteKit SSR

Anonymous users and `identify`

Next steps

SSR patterns

Canonical experiments

​Installation

​Setup

​Resolving parameters

​Setting context

​SvelteKit SSR

​Anonymous users and identify

​Next steps

SSR patterns

Canonical experiments

Installation

Setup

Resolving parameters

Setting context

SvelteKit SSR

Anonymous users and `identify`

Next steps