fix: replace express-ws with native ws to fix WebSocket binary handling

express-ws bundles ws@7.5.10 while @hocuspocus /server requires ws@8.x.
This version mismatch causes ERR_ENCODING_INVALID_ENCODED_DATA errors
as the binary Yjs protocol messages get corrupted passing through
express-ws's incompatible ws instance.

Replace express-ws with native http.createServer + ws.WebSocketServer
handling the upgrade event directly. This ensures a single ws@8.20.0
is used throughout, matching what Hocuspocus expects.

Made-with: Cursor

backend/package-lock.json

@@ -34,17 +34,17 @@
         "ai": "^6.0.158",
         "dotenv": "^17.4.1",
         "express": "^4.21.0",
-        "express-ws": "^5.0.2",
         "lowlight": "^3.3.0",
         "multer": "^2.1.1",
+        "ws": "^8.20.0",
         "yjs": "^13.6.0",
         "zod": "^4.3.6"
       },
       "devDependencies": {
         "@types/express": "^5.0.0",
-        "@types/express-ws": "^3.0.5",
         "@types/multer": "^2.1.0",
         "@types/node": "^22.0.0",
+        "@types/ws": "^8.18.1",
         "tsx": "^4.19.0",
         "typescript": "^5.6.0"
       }
@@ -1301,18 +1301,6 @@
         "@types/send": "*"
       }
     },
-    "node_modules/@types/express-ws": {
-      "version": "3.0.6",
-      "resolved": "https://registry.npmjs.org/@types/express-ws/-/express-ws-3.0.6.tgz",
-      "integrity": "sha512-6ZDt+tMEQgM4RC1sMX1fIO7kHQkfUDlWfxoPddXUeeDjmc+Yt/fCzqXfp8rFahNr5eIxdomrWphLEWDkB2q3UQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/express": "*",
-        "@types/express-serve-static-core": "*",
-        "@types/ws": "*"
-      }
-    },
     "node_modules/@types/hast": {
       "version": "3.0.4",
       "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz",
@@ -1941,7 +1929,6 @@
       "resolved": "https://registry.npmjs.org/express/-/express-4.22.1.tgz",
       "integrity": "sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "accepts": "~1.3.8",
         "array-flatten": "1.1.1",
@@ -1983,42 +1970,6 @@
         "url": "https://opencollective.com/express"
       }
     },
-    "node_modules/express-ws": {
-      "version": "5.0.2",
-      "resolved": "https://registry.npmjs.org/express-ws/-/express-ws-5.0.2.tgz",
-      "integrity": "sha512-0uvmuk61O9HXgLhGl3QhNSEtRsQevtmbL94/eILaliEADZBHZOQUAiHFrGPrgsjikohyrmSG5g+sCfASTt0lkQ==",
-      "license": "BSD-2-Clause",
-      "dependencies": {
-        "ws": "^7.4.6"
-      },
-      "engines": {
-        "node": ">=4.5.0"
-      },
-      "peerDependencies": {
-        "express": "^4.0.0 || ^5.0.0-alpha.1"
-      }
-    },
-    "node_modules/express-ws/node_modules/ws": {
-      "version": "7.5.10",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-7.5.10.tgz",
-      "integrity": "sha512-+dbF1tHwZpXcbOJdVOkzLDxZP1ailvSxM6ZweXTegylPny803bFhA+vqBYw4s31NSAk4S2Qz+AKXK9a4wkdjcQ==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=8.3.0"
-      },
-      "peerDependencies": {
-        "bufferutil": "^4.0.1",
-        "utf-8-validate": "^5.0.2"
-      },
-      "peerDependenciesMeta": {
-        "bufferutil": {
-          "optional": true
-        },
-        "utf-8-validate": {
-          "optional": true
-        }
-      }
-    },
     "node_modules/fetch-ponyfill": {
       "version": "7.1.0",
       "resolved": "https://registry.npmjs.org/fetch-ponyfill/-/fetch-ponyfill-7.1.0.tgz",

backend/package.json

@@ -35,17 +35,17 @@
     "ai": "^6.0.158",
     "dotenv": "^17.4.1",
     "express": "^4.21.0",
-    "express-ws": "^5.0.2",
     "lowlight": "^3.3.0",
     "multer": "^2.1.1",
+    "ws": "^8.20.0",
     "yjs": "^13.6.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
-    "@types/express-ws": "^3.0.5",
     "@types/multer": "^2.1.0",
     "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0"
   }

backend/src/server.ts

@@ -1,6 +1,7 @@
 import "dotenv/config";
 import express from "express";
-import expressWebsockets from "express-ws";
+import { createServer } from "http";
+import { WebSocketServer } from "ws";
 import { Hocuspocus } from "@hocuspocus/server";
 import { Database } from "@hocuspocus/extension-database";
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
@@ -100,7 +101,8 @@ const hocuspocus = new Hocuspocus({
   ],
 });
 
-const { app } = expressWebsockets(express());
+const app = express();
+const httpServer = createServer(app);
 
 app.use(express.json({ limit: "1mb" }));
 
@@ -143,11 +145,19 @@ app.get("/api/auth/status", async (req, res) => {
   });
 });
 
-// ---------- Collab WebSocket ----------
+// ---------- Collab WebSocket (native ws upgrade, no express-ws) ----------
 
-app.ws("/collab/:doc", (ws, req) => {
-  const token = extractToken(req.headers.cookie);
-  hocuspocus.handleConnection(ws, req, { token });
+const wss = new WebSocketServer({ noServer: true });
+
+httpServer.on("upgrade", (req, socket, head) => {
+  if (req.url?.startsWith("/collab/")) {
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      const token = extractToken(req.headers.cookie);
+      hocuspocus.handleConnection(ws, req, { token });
+    });
+  } else {
+    socket.destroy();
+  }
 });
 
 // ---------- AI Chat ----------
@@ -384,7 +394,7 @@ if (existsSync(staticDir)) {
 
 // ---------- Start ----------
 
-const server = app.listen(PORT, () => {
+const server = httpServer.listen(PORT, () => {
   console.log(`[server] running on http://localhost:${PORT}`);
   console.log(`[server] collab websocket at ws://localhost:${PORT}/collab/:doc`);
 });