Skip to content

[Enhancement] Add first-class Bun runtime support with native WebSocket handling #502

@deepgram-robot

Description

@deepgram-robot

Summary

Add proper Bun runtime detection and native WebSocket handling so that Deepgram's JS SDK works correctly in Bun without workarounds, warnings, or silent failures — matching the first-class support already provided for Node.js and browser environments.

Problem it solves

Multiple open issues report problems running the SDK in Bun (#466: WebSocket connection fails silently, #401: repeated "Using WS Package" logging). Bun is one of the fastest-growing JavaScript runtimes and is increasingly used for server-side applications where speech-to-text is common. Currently, developers using Bun must apply workarounds or fall back to Node.js, which undermines Bun's performance benefits. Since Bun has a native WebSocket implementation that differs from both Node.js and browser WebSocket APIs, the SDK needs explicit Bun detection and appropriate WebSocket selection.

Proposed API

// No API change needed — Bun support should be transparent
import { createClient } from "@deepgram/sdk";

const deepgram = createClient(DEEPGRAM_API_KEY);

// These should "just work" in Bun without warnings or fallbacks
const live = deepgram.listen.live({ model: "nova-3" });
const agent = deepgram.agent.live({ model: "nova-3" });

Internal changes:

  • getGlobalWebSocket() should detect Bun runtime and use Bun's native WebSocket
  • Remove spurious "Using WS Package" warnings when running in Bun
  • Ensure WebSocket.send() binary handling matches Bun's implementation
  • Add Bun to the CI test matrix

Acceptance criteria

  • SDK initializes without warnings in Bun runtime
  • Live STT WebSocket connections work correctly in Bun
  • Voice Agent WebSocket connections work correctly in Bun
  • TTS WebSocket connections work correctly in Bun
  • No "Using WS Package" logging when running in Bun
  • Documented with Bun-specific notes in README
  • Compatible with existing API (no breaking changes)

Raised by the DX intelligence system.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions