unjs · pi0 · Jan 29, 2024 · Jan 29, 2024 · Jan 29, 2024 · Jan 29, 2024
diff --git a/.npmrc b/.npmrc
@@ -0,0 +1 @@
+ignore-workspace-root-check=true
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ Elegant HTTP listener!
 
 ## Features
 
-✅ Dev server with HMR, static, and typescript support with <a href="https://github.com/unjs/jiti">unjs/jiti</a><br>
+✅ Dev server with HMR, static, WebSockets and typescript support with <a href="https://github.com/unjs/jiti">unjs/jiti</a><br>
 
 ✅ Works with Node.js, express, and <a href="https://github.com/unjs/h3">unjs/h3</a> out of the box <br>
 
@@ -24,6 +24,8 @@ Elegant HTTP listener!
 
 ✅ Gracefully shutdown Server with <a href="https://github.com/thedillonb/http-shutdown">http-shutdown</a><br>
 
+✅ Zero Config WebSockets with <a href="https://github.com/unjs/crossws">unjs/crossws</a>
+
 ✅ Copy the URL to the clipboard<br>
 
 ✅ HTTPS support with self-signed certificates<br>
@@ -57,7 +59,10 @@ import { createApp, eventHandler } from "h3";
 
 export const app = createApp();
 
-app.use("/", eventHandler(() => "Hello world!"));
+app.use(
+  "/",
+  eventHandler(() => "Hello world!"),
+);
 ```
 
 or use npx to invoke `listhen` command:
@@ -193,6 +198,16 @@ Print QR Code for public address.
 
 When enabled, listhen tries to listen to all network interfaces. You can also enable this option using `--host` CLI flag.
 
+### `ws`
+
+- Default: `false`
+
+Enable experimental WebSocket support.
+
+Option can be a function for Node.js `upgrade` handler (`(req, head) => void`) or an Object to use [CrossWS Hooks](https://github.com/unjs/crossws).
+
+When using dev server CLI, you can easily use `--ws` and a named export called `webSocket` to define [CrossWS Hooks](https://github.com/unjs/crossws) with HMR support!
+
 ## License
 
 MIT. Made with 💖

diff --git a/package.json b/package.json
@@ -34,7 +34,7 @@
     "lint": "eslint --ext .ts . && prettier -c src test",
     "lint:fix": "eslint --fix --ext .ts . && prettier -w src test",
     "listhen": "node ./scripts/listhen.mjs",
-    "play": "node ./scripts/listhen.mjs -w ./playground",
+    "play": "node ./scripts/listhen.mjs -w ./playground --ws",
     "release": "pnpm test && pnpm build && changelogen --release && pnpm publish && git push --follow-tags",
     "test": "pnpm lint && vitest run --coverage"
   },
@@ -44,6 +44,7 @@
     "citty": "^0.1.5",
     "clipboardy": "^4.0.0",
     "consola": "^3.2.3",
+    "crossws": "^0.1.0",
     "defu": "^6.1.4",
     "get-port-please": "^3.1.2",
     "h3": "^1.10.1",
@@ -71,4 +72,4 @@
     "vitest": "^1.2.2"
   },
   "packageManager": "pnpm@8.15.0"
-}
+}
diff --git a/playground/index.ts b/playground/index.ts
@@ -1,8 +1,62 @@
 import { createApp, eventHandler } from "h3";
+import { defineWebSocketHooks } from "crossws";
 
 export const app = createApp();
 
+app.use(
+  "/ws",
+  eventHandler(() => {
+    return getWebSocketTestPage();
+  }),
+);
+
 app.use(
   "/",
   eventHandler(() => ({ hello: "world!" })),
 );
+
+function getWebSocketTestPage() {
+  return `
+  <!doctype html>
+  <head>
+    <title>WebSocket Test Page</title>
+  </head>
+  <body>
+    <div id="logs"></div>
+    <script type="module">
+      const url = \`ws://\${location.host}/_ws\`;
+      const logsEl = document.querySelector("#logs");
+      const log = (...args) => {
+        console.log("[ws]", ...args);
+        logsEl.innerHTML += \`<p>[\${new Date().toJSON()}] \${args.join(" ")}</p>\`;
+      };
+
+      log(\`Connecting to "\${url}""...\`);
+      const ws = new WebSocket(url);
+
+      ws.addEventListener("message", (event) => {
+        log("Message from server:", event.data);
+      });
+
+      log("Waiting for connection...");
+      await new Promise((resolve) => ws.addEventListener("open", resolve));
+
+      log("Sending ping...");
+      ws.send("ping");
+    </script>
+  </body>
+    `;
+}
+
+export const webSocket = defineWebSocketHooks({
+  open(peer) {
+    console.log("[ws] open", peer);
+    peer.send("Hello!");
+  },
+  message(peer, message) {
+    console.log("[ws] message", peer);
+    if (message.text() === "ping") {
+      peer.send("pong");
+    }
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/cli.ts b/src/cli.ts
@@ -57,6 +57,7 @@
       await listen(devServer.nodeListener, {
         ...opts,
         _entry: devServer._entry,
+        ws: opts.ws ? devServer._ws : undefined,
       });
       await devServer.reload(true);
     }
@@ -85,6 +86,10 @@
       type: "boolean",
       description: "Open the URL in the browser",
     },
+    ws: {
+      type: "boolean",
+      description: "Enable Experimental WebSocket support",
+    },
     https: {
       type: "boolean",
       description: "Enable HTTPS",

diff --git a/src/listen.ts b/src/listen.ts
@@ -129,6 +129,23 @@
     listhenOptions.port = _addr.port;
   }
 
+  // --- WebSocket ---
+  if (listhenOptions.ws) {
+    if (typeof listhenOptions.ws === "function") {
+      server.on("upgrade", listhenOptions.ws);
+    } else {
+      consola.warn(
+        "[listhen] Using experimental websocket API. Learn more: `https://crossws.unjs.io`",
+      );
+      const nodeWSAdapter = await import("crossws/adapters/node").then(
+        (r) => r.default || r,
+      );
+      // @ts-expect-error TODO
+      const { handleUpgrade } = nodeWSAdapter(listhenOptions.ws);
+      server.on("upgrade", handleUpgrade);
+    }
+  }
+
   // --- GetURL Utility ---
   const getURL = (host = listhenOptions.hostname, baseURL?: string) =>
     generateURL(host, listhenOptions, baseURL);

diff --git a/src/server/dev.ts b/src/server/dev.ts
@@ -4,12 +4,14 @@
 import { dirname, join, resolve } from "pathe";
 import type { ConsolaInstance } from "consola";
 import { resolve as _resolve } from "mlly";
+import type { WebSocketHooks } from "crossws";
 import { createResolver } from "./_resolver";
 
 export interface DevServerOptions {
   cwd?: string;
   staticDirs?: string[];
   logger?: ConsolaInstance;
+  ws?: boolean | Partial<WebSocketHooks>;
 }
 
 export async function createDevServer(
@@ -54,6 +56,28 @@
   // Create app instance
   const app = createApp();
 
+  // WebSocket
+  let _ws: Partial<WebSocketHooks> | undefined;
+  const webSocketHooks = Object.create(null);
+  if (options.ws) {
+    const createDynamicHook =
+      (name: string) =>
+      async (...args: any[]) => {
+        if (typeof options.ws === "object") {
+          await (options.ws as any)[name]?.(...args);
+        }
+        return (webSocketHooks as any)[name]?.(...args);
+      };
+    _ws = new Proxy(
+      {},
+      {
+        get(_, prop) {
+          return createDynamicHook(prop as string);
+        },
+      },
+    );
+  }
+
   // Register static asset handlers
   const staticDirs = (options.staticDirs || ["public"])
     .filter(Boolean)
@@ -122,9 +146,27 @@
           `🚀 Loading server entry ${resolver.formateRelative(_entry)}`,
         );
       }
-      let _handler = await resolver
-        .import(_entry)
-        .then((r) => r.handler || r.handle || r.app || r.default || r);
+
+      const _loadedEntry = await resolver.import(_entry);
+
+      let _handler =
+        _loadedEntry.handler ||
+        _loadedEntry.handle ||
+        _loadedEntry.app ||
+        _loadedEntry.default ||
+        _loadedEntry;
+
+      if (options.ws) {
+        Object.assign(
+          webSocketHooks,
+          _loadedEntry.webSocket ||
+            _loadedEntry.websocket ||
+            _handler.webSocket ||
+            _handler.websocket ||
+            {},
+        );
+      }
+
       if (_handler.handler) {
         _handler = _handler.handler; // h3 app
       }
@@ -153,6 +195,7 @@
     resolver,
     nodeListener: toNodeListener(app),
     reload: (_initial?: boolean) => loadHandle(_initial),
+    _ws,
     _entry: resolveEntry(),
   };
 }

diff --git a/src/server/watcher.ts b/src/server/watcher.ts
@@ -22,14 +22,15 @@
 
   // Create dev server
   const devServer = await createDevServer(entry, {
-    cwd: options.cwd,
+    ...options,
     logger,
   });
 
   // Initialize listener
   const listenter = await listen(devServer.nodeListener, {
     ...options,
     _entry: devServer._entry,
+    ws: options.ws ? devServer._ws : undefined,
   });
 
   // Load dev server handler first time

diff --git a/src/types.ts b/src/types.ts
@@ -1,7 +1,8 @@
-import type { Server } from "node:http";
+import type { IncomingMessage, Server } from "node:http";
 import type { Server as HTTPServer } from "node:https";
 import { AddressInfo } from "node:net";
 import type { GetPortInput } from "get-port-please";
+import type { WebSocketHooks } from "crossws";
 
 export interface Certificate {
   key: string;
@@ -52,6 +53,18 @@ export interface ListenOptions {
    * Open a tunnel using https://github.com/unjs/untun
    */
   tunnel?: boolean;
+  /**
+   * WebSocket Upgrade Handler
+   *
+   * Input can be an upgrade handler or CrossWS options
+   *
+   * @experimental CrossWS usage is subject to change
+   * @see https://github.com/unjs/crossws
+   */
+  ws?:
+    | boolean
+    | Partial<WebSocketHooks>
+    | ((req: IncomingMessage, head: Buffer) => void);
 }
 
 export type GetURLOptions = Pick<