elevenlabs-local-dev-loop

name	elevenlabs-local-dev-loop
description	Use when setting up a local ElevenLabs dev environment for a TTS/voice project and you need SDK mocking, hot reload, quota-aware iteration, and audio-output testing that does not burn character quota during development. Trigger with "elevenlabs dev setup", "elevenlabs local development", "elevenlabs dev environment", "develop with elevenlabs", "test elevenlabs locally".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(pnpm:*)
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","voice","ai","elevenlabs","tts","testing"]
compatibility	Designed for Claude Code

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.

1. 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.

2. Environment configuration — write an environment-aware config.ts that picks the model and output format by NODE_ENV. This is the essential skeleton:

   // src/elevenlabs/config.ts
   export function loadConfig() {
     const env = process.env.NODE_ENV || "development";
     return {
       : process.. || ,
       
       : env === 
         ?    
         : ,       
       : process.. || ,
       : ,  
     };
   }