Svelte SDK

The @tracio/svelte package wraps the core @tracio/sdk and exposes idiomatic Svelte primitives: a one-time init call, and readable stores that hand you the visitor ID and identification result.

Installation

npm install @tracio/svelte @tracio/sdk

svelte (5) is a peer dependency and is expected to already be installed in your app.

Setup

Call Tracio.init({ publicKey }) once, near the root of your app — in +layout.svelte for SvelteKit — guarded by browser so it never runs during server-side rendering.

<!-- +layout.svelte -->
<script>
  import { Tracio } from "@tracio/svelte"
  import { browser } from "$app/environment"
  if (browser) Tracio.init({ publicKey: import.meta.env.VITE_TRACIO_KEY })
</script>
<slot />

Stores

TRACIO state is exposed as Svelte readable stores. Each store value is a QueryState carrying data, isLoading, and error. Consume the store with the $ prefix: $visitor.data, $visitor.isLoading, $visitor.error.

Coming from React? Svelte's QueryState omits the React hooks' isFetched flag, and useVisitorId() does not expose an imperative fetch method — only useTracioResult() carries a getData().

useVisitorId()

Returns a readable store of { data, isLoading, error }, where data is the stable visitor identifier (string | undefined).

<script>
  import { useVisitorId } from "@tracio/svelte"
  const visitor = useVisitorId()
</script>
{$visitor.data}

useTracioResult(opts?)

Returns a readable store of { data, isLoading, error } holding the full TracioResult (visitor ID plus bot detection). The returned store also carries a getData() method (it extends Readable) for imperative (re-)fetching. opts.immediate defaults to true; pass { immediate: false } to defer the fetch until you call getData() — for example behind a consent gate.

<script>
  import { useTracioResult } from "@tracio/svelte"
  const result = useTracioResult({ immediate: false })
  // $result.data / $result.isLoading / $result.error
  // result.getData(): Promise<void> — call to fetch on demand
</script>

useTracio()

Escape hatch that returns the underlying TracioInstance (or undefined when Tracio.init() has not run for the current tree) for advanced use. It returns the instance directly — there is no store or wrapper object to destructure.

<script>
  import { useTracio } from "@tracio/svelte"
  const tracio = useTracio()
</script>

Full example

<!-- +layout.svelte -->
<script>
  import { Tracio } from "@tracio/svelte"
  import { browser } from "$app/environment"
  if (browser) Tracio.init({ publicKey: import.meta.env.VITE_TRACIO_KEY })
</script>
<slot />

<!-- AnyComponent.svelte -->
<script>
  import { useVisitorId } from "@tracio/svelte"
  const visitor = useVisitorId()
</script>
{#if $visitor.isLoading}Loading…{:else if $visitor.error}Error: {$visitor.error.message}{:else}Visitor: {$visitor.data}{/if}

Next steps

• JavaScript SDK Reference — the core @tracio/sdk API the stores build on
• Error Handling — error codes and retry strategies
• SDKs overview — every framework package at a glance