Developer Setup & Scripts

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• AGENTS.md
• README.md
• src/index.ts
• src/tests/e2e/openai.e2e.test.ts

This page outlines the development environment, tooling, and command-line interfaces required to contribute to the @speech-sdk/core repository. It covers the project's strict TypeScript environment, testing strategies, and the scripts used to maintain high code quality across the SDK's multi-provider architecture.

The project is an ESM-only universal TTS SDK that runs across Node.js, Edge, and Browser environments. It utilizes pnpm for package management and biome (via ultracite) for formatting and linting.

Sources: AGENTS.md:16-18, package.json:2-10

Environment Requirements & Setup

The SDK requires pnpm for managing dependencies and executing lifecycle scripts. The project adheres to a strict ESM configuration and targets the ES2022 JavaScript version.

Initial Installation

To set up the local development environment, developers must install dependencies using:

pnpm install

Sources: AGENTS.md:5, package.json:6

Project Constraints

The development environment is governed by several core constraints:

• Module System: Pure ESM ("type": "module").
• TypeScript: Strict mode enabled, targeting ES2022.
• Dependencies: Zero runtime dependencies except for p-retry and mediabunny.
• Formatting: Enforced by Biome via ultracite.

Sources: AGENTS.md:27-33, package.json:115-116

Available Development Scripts

The package.json defines a set of scripts for building, testing, and maintaining the codebase.

Script	Command	Description
build	tsc	Compiles TypeScript source code to the dist directory.
test	vitest run	Executes unit tests in src/__tests__/*.test.ts.
test:watch	vitest	Runs tests in watch mode for active development.
test:e2e	vitest run --config vitest.config.e2e.ts	Runs end-to-end tests against real provider APIs.
typecheck	tsc --noEmit	Validates types without generating output files.
check	ultracite check	Inspects code for linting and formatting issues.
fix	ultracite fix	Automatically applies linting and formatting fixes using Biome.

Sources: package.json:101-107, AGENTS.md:5-13

Testing Architecture

The project employs a dual-layered testing strategy using vitest with globals enabled.

Unit Testing

Unit tests are located in src/__tests__/*.test.ts. These tests typically mock the fetch API to verify that provider implementations send the correct headers, URLs, and JSON payloads without making real network requests.

End-to-End (E2E) Testing

E2E tests reside in src/__tests__/e2e/*.e2e.test.ts. These tests interact with live provider APIs and require valid API keys.

E2E Configuration Flow

The following diagram illustrates the requirements for running E2E tests:

The SDK utilizes a .env file or shell exports to provide keys like OPENAI_API_KEY or ELEVENLABS_API_KEY to the test suite.

Sources: AGENTS.md:15-16, src/tests/e2e/openai.e2e.test.ts:7-10, package.json:120

Code Standards & Contribution Workflow

Developers must adhere to specific coding standards before committing code. A Husky pre-commit hook is utilized to automatically run tests and lint checks.

Contribution Sequence

1. Implement Feature: Follow the provider pattern (Factory function -> ResolvedModel).
2. Add Tests: Create corresponding .test.ts and .e2e.test.ts files.
3. Format Code: Run pnpm fix to ensure compliance with Biome rules.
4. Type Verification: Run pnpm run typecheck.
5. Final Check: Execute pnpm test to ensure no regressions.

Key Implementation Rules

• Prefer unknown over any.
• Use const assertions (as const) for immutable values like model language lists.
• Use async/await instead of Promise chains.
• Throw Error objects with descriptive messages rather than strings.

Sources: AGENTS.md:32-58, src/index.ts:1-35

Build and Export Configuration

The project uses a sophisticated exports map in package.json to support subpath imports, allowing users to import specific providers or features without loading the entire SDK.

This structure ensures that the build artifacts in ./dist are correctly mapped to their TypeScript type definitions for consumer applications.

Sources: package.json:15-98

The developer setup for @speech-sdk/core is designed for high reliability and type safety. By utilizing strict TypeScript configurations, automated formatting via Biome, and a comprehensive testing suite that balances mocks with real-world E2E verification, the project maintains a stable environment for supporting its 13+ TTS providers.