Skip to content

WebSocket compatibility issue with Bun runtime #1003

@afnan-davia

Description

@afnan-davia

Description
Hocuspocus server's handleConnection method is incompatible with Bun's WebSocket implementation when used through the Elysia framework. Bun's WebSocket follows the standard Web API specification, while Hocuspocus expects a Node.js-specific WebSocket interface, leading to runtime errors when attempting to establish connections.

Steps to reproduce the bug
Steps to reproduce the behavior:

  1. Create a new Elysia project with bun create elysia app and install Hocuspocus server
  2. Set up an Elysia application with WebSocket support using @elysiajs/websocket
  3. Attempt to pass the Elysia WebSocket connection to hocuspocus.handleConnection()
  4. Observe connection failures due to incompatible WebSocket interfaces
    Code example:
import { Elysia } from 'elysia';
import { ws } from '@elysiajs/websocket';
import { Hocuspocus } from '@hocuspocus/server';

const hocuspocus = new Hocuspocus({
  name: 'collaboration'
});

const app = new Elysia()
  .use(ws())
  .ws('/collaboration', {
    open(ws) {
      // Connection fails - incompatible WebSocket interface
      hocuspocus.handleConnection(ws.raw, ws.data.request);
    }
  })
  .listen(3000);

Expected behavior
Hocuspocus should natively support WebSocket implementations that conform to the standard Web API specification, including those provided by Bun runtime through frameworks like Elysia, without requiring additional adapters or modifications.

Environment?

  • operating system: MacOS Tahoe 26.0.1
  • runtime: Bun
  • browser: Google Chrome
  • framework: Elysia
  • Hocuspocus version: 3.2.3

Additional context
This compatibility issue prevents Bun users from integrating Hocuspocus for real-time collaborative features. The root cause is the architectural difference between Node.js-specific WebSocket implementations and the standard Web API that Bun follows.
For Hocuspocus to work seamlessly across modern JavaScript runtimes (Node.js, Deno, Bun, and browsers), it should abstract away these implementation differences by supporting the standard Web API WebSocket interface alongside Node.js conventions.

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions