ElevenLabs Local Dev Loop
Overview
Set up a fast, cost-effective local development workflow for ElevenLabs audio
projects. The loop centers on three moves — mock the SDK so unit tests never
burn character quota, gate real API calls behind an explicit
ELEVENLABS_INTEGRATION=1 flag, and select a cheaper model in dev while keeping
the high-quality model for production — with tsx watch hot reload and a quota
checker to round out the cycle.
Follow the high-level flow below to scaffold the project, then drill into
references/implementation.md for the full code
of every step and references/examples.md for worked
end-to-end runs.
Prerequisites
Before starting, confirm your environment is ready:
- The
elevenlabs-install-auth setup is complete, so the SDK
(@elevenlabs/elevenlabs-js) is installed and ELEVENLABS_API_KEY is
available in .env.local.
- Node.js 18+ with
npm or pnpm.
vitest installed as the test runner (recommended) — it powers the mock
layer and the integration-test guard.
Instructions
Work through the six steps in order. Each is summarized here; the full code for
every step lives in references/implementation.md.
-
Project structure — lay out src/elevenlabs/ (client, config, tts),
tests/__mocks__/ and tests/fixtures/sample.mp3, a git-ignored output/,
and .env.local / .env.example. Full tree in the reference.
-
Environment configuration — write an environment-aware config.ts that
picks the model and output format by NODE_ENV. This is the essential
skeleton:
export function loadConfig() {
const env = process.env.NODE_ENV || "development";
return {
apiKey: process.env.ELEVENLABS_API_KEY || "",
modelId: env === "production"
? "eleven_multilingual_v2"
: "eleven_flash_v2_5",
defaultVoiceId: process.env.ELEVENLABS_VOICE_ID || "21m00Tcm4TlvDq8ikWAM",
outputFormat: "mp3_22050_32",
};
}
-
Mock the SDK — write tests/__mocks__/elevenlabs.ts that returns the
sample.mp3 fixture from textToSpeech.convert/stream and stubs
voices.getAll and user.get, so unit tests cost nothing.
-
Development scripts — add dev (tsx watch), test, test:watch,
test:integration, generate, and quota scripts to package.json.
-
Quota-aware development — add src/check-quota.ts that reads
user.subscription and exits non-zero when fewer than 1000 characters
remain, so a low balance fails fast.
-
Integration test guard — write tests/tts.test.ts where the real-API
test is it.skipIf(!useRealApi) and only runs under
ELEVENLABS_INTEGRATION=1; the mocked test always runs.
See references/implementation.md for the
complete, copy-pasteable code for each step.
Output
- Working development environment with hot reload via
tsx watch
- Mock layer that avoids API calls and character charges during dev
- Quota checker to prevent surprise billing
- Integration test guard pattern (
ELEVENLABS_INTEGRATION=1)
- Environment-aware model selection (cheap in dev, quality in prod)
Error Handling
| Error | Cause | Solution |
|---|
MODULE_NOT_FOUND | SDK not installed | npm install @elevenlabs/elevenlabs-js |
| Mock returns undefined | Mock not wired | Check vi.mock path matches import |
| Integration test fails | No API key | Set ELEVENLABS_API_KEY in .env.local |
| Quota exceeded in dev | Running real API calls | Use mock layer; run npm run quota first |
Examples
Four worked runs of the loop — full walkthroughs in
references/examples.md:
- Zero-cost unit tests —
npm run test drives the service through the mock
client, passes offline, and never touches the API or your quota.
- Quota preflight —
npm run quota prints Characters: 500 / 10,000 (5.0% used) and exits 1 when fewer than 1000 characters remain, blocking a paid
run before it starts.
- Opt-in integration run —
npm run test:integration sets
ELEVENLABS_INTEGRATION=1, flipping the it.skipIf(!useRealApi) test on so
the real API is hit only when you ask for it.
- Hot-reload iteration —
npm run dev (tsx watch) restarts on save; with
the dev model (eleven_flash_v2_5) and mocks, each loop stays fast and free.
Resources
Next Steps
Once the dev loop is running, move on to production-ready code: see the
elevenlabs-sdk-patterns skill for streaming, retries, and voice-management
patterns you can layer on top of this environment.
