OpenHands / OpenHands/software-agent-sdk

Fix WebSocket client require('ws') breaking bundlers

Open
#4,731 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Python
Stars
1.1k
Forks
539
Avg merge
1d 19h
Merged PRs (30d)
137

Description

Problem

src/events/websocket-client.ts uses require('ws') in library code:

if (typeof window !== 'undefined' && window.WebSocket) {
  WebSocketImpl = window.WebSocket;
} else {
  const ws = require('ws');
  WebSocketImpl = ws;
}

Problems:

  1. require() breaks ES module bundlers (Webpack, Rollup, Vite) — they statically analyze imports
  2. The detection runs at module load time, so the require('ws') executes immediately in Node.js even if the WebSocket client is never used
  3. Contradicts the browser-compatibility requirement in AGENTS.md
  4. Has an eslint-disable comment for @typescript-eslint/no-require-imports

Proposed Fix

Options:

  1. Constructor injection (recommended) — accept WebSocket implementation via constructor options:

    constructor(options: WebSocketClientOptions & { WebSocket?: typeof WebSocket }) {
      this.WebSocketImpl = options.WebSocket ?? globalThis.WebSocket;
    }
    

    Node.js users pass ws, browser users get native WebSocket automatically.

  2. Dynamic import — use await import('ws') behind an async factory method

  3. Just use native WebSocket — Node.js 21+ has native WebSocket support. Document minimum Node version requirement.

Impact

Medium — currently breaks Vite/Webpack/Rollup builds that include this library.


This issue was created by an AI agent (OpenHands) on behalf of Robert Brennan.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/events/websocket-client.ts and the browser-compatibility requirement in AGENTS.md. Compare the constructor-injection, dynamic-import, and native-WebSocket options against the library's existing API and bundler constraints. Done means the client no longer relies on module-load-time require('ws') and Webpack, Rollup, and Vite builds can include it.

Written by the indexing model from the issue text.

Assessment

Tech stack
rollup, typescript, vite, webpack
Domain
web-dev
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.