Your WebSocket Server Shouldn't Break When You Switch Runtimes

Stop Rewriting Your WebSocket Server for Every Runtime

If you've ever shipped a WebSocket server and then watched it fall apart the moment someone wanted to run it on Deno, or Bun, or a Cloudflare Worker, you already know the pain. The WebSocket API looks deceptively similar across runtimes until it isn't. Upgrade handling, message framing, connection lifecycle hooks — every platform has its own opinions, and the differences are just sharp enough to cost you a full afternoon you didn't budget for.

That's the problem crossws solves, and it solves it cleanly.

What CrossWS Actually Is

CrossWS is a small, typed toolkit for building WebSocket servers that run across Node.js, Bun, Deno, and edge runtimes without you having to touch your core logic between deployments. One API, consistent behavior, full TypeScript support.

The abstraction is minimal on purpose. You're not buying into a framework. You're getting a thin, stable layer that handles the platform-specific wiring so your application code stays clean.

What the API Looks Like

Here's a basic example that shows how little boilerplate you're dealing with:

import { defineWebSocketHandler } from "crossws";

const handler = defineWebSocketHandler({
  open(peer) {
    console.log("Connection opened:", peer.id);
    peer.send("Welcome!");
  },

  message(peer, message) {
    console.log("Received:", message.text());
    peer.send(`Echo: ${message.text()}`);
  },

  close(peer, details) {
    console.log("Connection closed:", details.code);
  },

  error(peer, error) {
    console.error("Error:", error);
  },
});

That handler works on Node.js with ws, on Bun's native WebSocket server, on Deno, and on edge adapters like Cloudflare Workers. You swap the adapter, not the logic. The hooks are typed, the peer object is consistent, and the surface area is small enough that you can read the whole API in a sitting.

Why This Matters More Than It Looks

The real cost of WebSocket portability problems isn't the initial rewrite. It's the maintenance burden that builds up over time. You end up with adapter logic scattered through your codebase, conditional branches based on runtime detection, and tests that only cover one environment. When requirements change or you want to move to a faster runtime, the cleanup is painful.

CrossWS cuts that off at the root. When your connection handling logic is decoupled from the runtime, you can make infrastructure decisions independently. Want to benchmark Bun against Node.js for a latency-sensitive feature? Swap the adapter in one place and run your tests. That's the kind of flexibility that matters when you're operating real-time infrastructure at any meaningful scale.

At Turboline, reliable real-time data streaming starts at the connection layer. Tools like CrossWS represent exactly the right philosophy: keep the abstractions thin, keep the types tight, and don't force application developers to become experts in runtime-specific WebSocket internals just to ship something stable.

The Concrete Takeaway

If you're building anything that touches WebSockets and you care about runtime portability, CrossWS is worth an hour of your time right now. The typed hooks alone will save you debugging sessions. The adapter model will save you rewrites later.

Sometimes the best infrastructure decision is the one that removes a whole category of future problems. This is one of those.