Svelte SDK

The @yak-io/svelte package provides a Svelte-compatible provider for integrating Yak. It exposes Svelte readable stores for reactive state and explicit mount()/destroy() methods for lifecycle control.

Installation

npm install @yak-io/svelte @yak-io/javascript

pnpm add @yak-io/svelte @yak-io/javascript

yarn add @yak-io/svelte @yak-io/javascript

bun add @yak-io/svelte @yak-io/javascript

Quick Start

Set up the provider in your root component

Call createYakProvider and wire up mount()/destroy() to Svelte's lifecycle:

<!-- App.svelte -->
<script lang="ts">
import { onMount, onDestroy } from "svelte";
import { createYakProvider } from "@yak-io/svelte";

const yak = createYakProvider({
  appId: "your-app-id",
  getConfig: async () => {
    const res = await fetch("/api/yak");
    return res.json();
  },
  onToolCall: async (name, args) => {
    const res = await fetch("/api/yak", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ name, args }),
    });
    const data = await res.json();
    if (!data.ok) throw new Error(data.error);
    return data.result;
  },
});

onMount(() => yak.mount());
onDestroy(() => yak.destroy());
</script>

<slot />

Set up server handlers

Use @yak-io/javascript to create the API endpoints on your backend. See the JavaScript SDK for runtime-specific examples (Express, Hono, Cloudflare Workers, etc.).

// api/yak.ts
import { createYakHandler } from "@yak-io/javascript/server";

export const { GET, POST } = createYakHandler({
  routes: [
    { path: "/", title: "Home" },
    { path: "/products", title: "Products" },
  ],
});

API

createYakProvider

Creates a Yak widget instance with Svelte-compatible stores. Unlike the Vue and React SDKs, the Svelte SDK does not use framework-level context — you manage the lifecycle explicitly with mount() and destroy().

Option	Type	Required	Description
`appId`	`string`	Yes	Your Yak application ID
`mode`	`"chat" \| "voice" \| "both"`	No	Which surfaces the trigger exposes. Defaults to `"chat"`. See Voice Mode.
`getConfig`	`() => Promise<ChatConfig> \| ChatConfig`	No	Config provider for routes and tools (used by chat and voice)
`onToolCall`	`(name, args) => Promise<unknown>`	No	Handler for tool execution (used by chat and voice)
`theme`	`Theme`	No	Widget styling options
`onRedirect`	`(path: string) => void`	No	Custom navigation handler
`disableRestartButton`	`boolean`	No	Hide the restart button in the header
`disablePageContent`	`boolean`	No	Stop sending any page context (URL, title, and visible text) to the assistant. The widget still works, but it won't be aware of the page the user is on.
`trigger`	`boolean \| TriggerButtonConfig`	No	Configure the floating trigger button
`user`	`{ id, hash }`	No	Signed end-user identity. Enables conversation persistence and history. Call `setUser()` to change it after setup (login/logout).

Privacy: By default Yak shares the current page's URL, title, and visible text with the assistant so it can answer questions about the page the user is viewing. Set disablePageContent to turn this off entirely — the SDK then sends nothing about the page (not even the URL), so the assistant can't answer page-specific questions.

Return value (`YakApi`)

Property	Type	Description
`isOpen`	`Readable<boolean>`	Whether the chat panel is currently open
`isReady`	`Readable<boolean>`	Whether the widget iframe is ready
`chatLoading`	`Readable<boolean>`	`isOpen && !isReady` — opening but not yet interactive
`open`	`() => void`	Open the chat panel
`close`	`() => void`	Close the chat panel
`openWithPrompt`	`(prompt: string) => void`	Open and send a specific prompt
`subscribeToToolEvents`	`(handler) => () => void`	Subscribe to tool call events (returns unsubscribe)
`voiceMachine`	`Readable<VoiceMachine>`	Current voice state — see Voice Mode
`voiceLoading`	`Readable<boolean>`	`true` while the voice session is connecting
`voiceStart`	`() => Promise<void>`	Start a voice session
`voiceStop`	`() => Promise<void>`	Stop the current voice session
`voiceToggle`	`() => Promise<void>`	Start if idle/error, stop if active
`setUser`	`(user?: { id, hash }) => void`	Set or clear the signed end-user identity after setup — call on login/logout
`mount`	`() => void`	Mount the widget DOM — call in `onMount`
`destroy`	`() => void`	Destroy the widget DOM — call in `onDestroy`

Reactive State

isOpen and isReady are Svelte readable stores. Access their values with the $ prefix in templates or subscribe manually:

<script lang="ts">
const { isOpen, isReady, open, close } = yak;
</script>

<button on:click={() => open()}>Open Chat</button>
{#if $isOpen}
  <button on:click={() => close()}>Close</button>
{/if}
<p>Ready: {$isReady}</p>

Tool Events

Subscribe to tool call completion events for UI synchronization:

<script lang="ts">
import { onDestroy } from "svelte";

const unsubscribe = yak.subscribeToToolEvents((event) => {
  if (event.ok && event.name.startsWith("order.")) {
    refreshOrders();
  }
});

onDestroy(unsubscribe);
</script>

Router Integration

Pass SvelteKit's navigation function to onRedirect for client-side navigation:

<script lang="ts">
import { goto } from "$app/navigation";
import { createYakProvider } from "@yak-io/svelte";

const yak = createYakProvider({
  appId: "your-app-id",
  onRedirect: (path) => goto(path),
  // ...other options
});
</script>