Introduction

If you are migrating a SvelteKit app to support realtime avatars, the hard part is usually not the avatar vendor itself. The hard part is keeping SvelteKit’s routing model, client-side state, and WebSocket lifecycle from fighting each other.

In practice, you need three things to line up:

• session state that survives navigation without leaking across users,

• route-aware component mounting so the avatar and transport are initialized exactly once,

• WebSocket or WebRTC cleanup that happens reliably on teardown, not “eventually”.

This checklist walks through the pieces that usually break during a migration, and how to structure them so an avatar can talk, lip-sync, reconnect, and shut down cleanly in SvelteKit.

Start by deciding where the realtime session lives

Before touching routing code, decide what “session” means in your app. A realtime avatar session is not the same thing as a Svelte route state or a browser tab state. It usually represents a server-issued capability object plus some ephemeral connection metadata: session ID, transport token, active model or voice settings, and a lifecycle that may outlive a route change.

The safest pattern is to keep server-authoritative session creation on the server and only hydrate the browser with the minimum data it needs to connect. In SvelteKit, that usually means:

1. create or fetch the avatar session in a +page.server.ts or +layout.server.ts load function,

2. pass the narrow connection payload down to the page,

3. instantiate the realtime transport only in a client-only component.

Do not stash long-lived transport objects in a module-level singleton unless you are deliberately building a global app-wide connection. SvelteKit’s server can render multiple requests in the same process, so module state is shared. That is fine for caches; it is a bug for per-user avatar sessions.

Use route boundaries deliberately

SvelteKit reuses layouts aggressively. That is good for performance, but it means your avatar component may stay mounted while children swap out, or it may be torn down when you expected it to persist. The migration checklist should answer two questions for each route:

• Should this avatar persist across child route navigation?

• Should its connection survive a full page transition, or should it reconnect per route?

If the answer is “persist,” mount the avatar in a shared layout rather than a page component. If the answer is “reconnect per route,” keep it page-scoped and make teardown explicit.

For SvelteKit, the practical rule is simple: if the avatar owns the connection, create it in the component that owns the UI, and destroy it in that component’s cleanup. Avoid creating a transport in a parent layout while the DOM node that renders video lives in a child page; that split makes it too easy to leak subscriptions or render into a detached element.

State: keep UI state separate from connection state

A realtime avatar usually has at least three different kinds of state:

• UI state: open/closed, muted/unmuted, selected voice, active tab.

• Connection state: connecting, connected, reconnecting, disconnected, errored.

• Conversation state: transcript, partial speech, agent turn-taking, playback progress.

Do not collapse these into one Svelte store. If you do, every transient socket event will rerender your UI as if the user had changed a form field. Keep the connection object separate from the derived UI state, then expose a small set of readable stores or component locals for rendering.

A robust pattern is:

import { writable, derived } from 'svelte/store';

export const isLive = derived(connectionState, ($s) => $s === 'connected');

import { writable, derived } from 'svelte/store';

export const isLive = derived(connectionState, ($s) => $s === 'connected');

import { writable, derived } from 'svelte/store';

export const isLive = derived(connectionState, ($s) => $s === 'connected');

Keep the transport instance itself out of Svelte stores unless you have a good reason. Stores are for serializable state and UI subscriptions; WebSocket/WebRTC objects are imperative resources with their own lifecycle.

WebSocket and WebRTC lifecycle: the checklist that prevents leaks

Most realtime avatar bugs in a SvelteKit migration come from lifecycle mismatches, not from the underlying protocol. Whether you are using a plain WebSocket control channel, a media transport, or a voice-agent SDK that manages both, the teardown sequence should be explicit:

1. stop sending new user input,

2. detach event listeners,

3. close the signaling or socket connection,

4. stop any media tracks, if you created them,

5. clear timers and retry loops.

In Svelte, put that logic in onDestroy for the component that owns the connection. If you are using bind:this to render into a video or canvas element, guard against late-arriving events after teardown. A common failure mode is a reconnect callback that fires after the component is gone and tries to write into a destroyed store or null DOM node.

Also be careful with reconnect loops. Realtime systems should reconnect on transient network failures, but in a routed app you need to distinguish “user navigated away” from “network dropped.” A destroyed component should cancel its reconnect timer. If you do not cancel, the app can quietly create a zombie socket after the route changes.

Handle browser-only code with SvelteKit’s SSR model in mind

SvelteKit renders on the server first. Anything that depends on window, document, MediaDevices, or WebRTC must stay on the client side. For avatar integrations, this is usually the transport bootstrap and any local media capture for voice input.

Use onMount or a {#if browser} guard to delay initialization. This is not just about avoiding reference errors; it also prevents the server from accidentally creating per-request objects that are meant to be browser-only.

Example pattern:

import { onMount, onDestroy } from 'svelte';

onDestroy(() => cleanup());

import { onMount, onDestroy } from 'svelte';

onDestroy(() => cleanup());

import { onMount, onDestroy } from 'svelte';

onDestroy(() => cleanup());

That shape is boring, which is exactly what you want. The goal is to make route changes and hot reloads uneventful.

Routing checklist for a migration

When moving an existing SvelteKit app onto a realtime avatar flow, I usually sanity-check these points in order:

• Session creation: server-side only, with narrowly scoped browser payloads.

• Mount point: one component owns the avatar DOM target and the transport.

• Persistence: decide whether the avatar should survive child route changes.

• Cleanup: disconnect on destroy, cancel retries, detach listeners.

• SSR safety: keep browser APIs out of load functions and server components.

• State separation: transport state, UI state, and transcript state are distinct.

If you already have a voice agent running, this checklist also applies when you add video lip-sync on top. The media layer should not change how the rest of your app thinks about routing and state.

Where Protoface fits

Protoface is useful here because it gives you a clean boundary between your app and the avatar runtime. In a SvelteKit migration, that means you can keep API-key-backed session creation off the client, then connect the browser to a realtime avatar session using the minimal data your page needs.

If your backend already orchestrates a voice agent, the LiveKit plugin is the most direct integration point; if you are wiring browser sessions yourself, the REST API and docs are the place to check the exact session payloads and authentication flow. For the browser-only embed path, the iframe model avoids exposing secrets in the app at all, which simplifies the SvelteKit side substantially.

curl -X POST https://api.protoface.com/<endpoint> \
-d '{"avatar_id":"...","voice":"..."}'

curl -X POST https://api.protoface.com/<endpoint> \
-d '{"avatar_id":"...","voice":"..."}'

curl -X POST https://api.protoface.com/<endpoint> \
-d '{"avatar_id":"...","voice":"..."}'

The exact request shape depends on the API surface you use, so treat that as an outline and verify the fields in the documentation.

Conclusion

The migration is mostly about discipline: keep session creation server-side, scope the avatar component to the right route boundary, separate state by responsibility, and make teardown explicit. If you do those four things, realtime avatars become another managed resource in SvelteKit instead of a source of intermittent leaks and reconnect bugs.

For implementation details, sample integrations, and the current API shape, start with docs.protoface.com and the relevant quickstart or SDK repo for your stack. Then wire the avatar into one route first, verify teardown on navigation, and expand from there.