Docs Install

Install

Requirements, package setup, server environment, and the one Tailwind setting the ready-made components need.

Requirements

Supported toolchain
Requirement	Version or note
`node`	22.17 or newer for the server build and package tooling
`bun`	1.4 or newer for the included scripts
`svelte`	5.x peer dependency
`sveltekit`	Optional. Needed only for the signed URL server route.
Browser	WebSocket; for voice, Web Audio, getUserMedia, and a secure context
ElevenLabs	An agent id and, for signed mode, a workspace API key

The microphone requires HTTPS or localhost. Browsers block getUserMedia in insecure contexts, and the controller reports that as an insecure-context error rather than failing without a message.

Install the package

bun add svelte-elevenlabs

With npm:

npm install svelte-elevenlabs

The package is ESM only and ships its TypeScript declarations. The root entry contains Svelte components, so use a Svelte-aware bundler. Node scripts, tests, and server code can import the Node-safe subpaths:

import { parseAudioFormat, resampleLinear } from 'svelte-elevenlabs/audio';import type { AudioFormat, ConversationOptions } from 'svelte-elevenlabs/types';

Published subpaths:

svelte-elevenlabs for the controller, audio engine, types, and components.
svelte-elevenlabs/audio for the framework-agnostic audio manager and helpers.
svelte-elevenlabs/types for the public type surface and ConversationError.
svelte-elevenlabs/package.json for tooling.

Environment

Signed mode needs one server-only secret. Public agent ids do not need a key, which is why the static showcase can connect without a server. Start from .env.example in this repository:

.env

# Server only. Never expose this through PUBLIC_*.ELEVENLABS_API_KEY=your_key_here# Optional and public. Prefills the showcase target field.PUBLIC_ELEVENLABS_AGENT_ID=agent_examplePublicId

Bun loads .env directly. The Node start script passes --env-file-if-exists=.env, so both runtimes read the same file. In a container or a hosting platform, set the values in the process environment instead.

Signed URL endpoint

The package defaults signedUrlEndpoint to /api/signed-url. The included SvelteKit route implements that contract and validates agent_ and seng_ ids. Read Signed URLs for the full route, the response shape, and the security checklist.

For a quick local start, copy the route from src/routes/api/signed-url/+server.ts in this repository, or use a public agent id and skip the server exchange entirely.

Tailwind discovery

No global stylesheet is required. The components use scoped styles and themeable CSS variables. If you use ConversationWidget or another ready-made component inside a Tailwind v4 app, make the package output discoverable so utility classes are generated:

app.css

@import 'tailwindcss';@source '../node_modules/svelte-elevenlabs/dist';

Scoped component styles do not require this line. It only tells Tailwind where to scan the package output for utility class names.

Verify the install

Import the controller in a component and run your type check. For this repository, that is bun run check.
Start the dev server on localhost or an HTTPS origin. Open the page in a browser that supports Web Audio.
Start a session from a click. The browser should ask for microphone permission and the controller should reach status === 'connected' after metadata negotiation.

If the connection fails, read Troubleshooting before changing the audio code. The controller publishes a stable errorCode for each failure category.

Edit this page on GitHub