next-ws 0.0.0-beta-20250822123253 → 0.0.0-beta-20250824054249

package/README.md

@@ -50,14 +50,14 @@ To set up a WebSocket server with `next-ws`, you need to patch your local Next.j
 
 ## 🚀 Usage
 
-Using WebSocket connections in your Next.js app directory is simple with `next-ws`. You can handle WebSocket connections directly in your API routes via exported `SOCKET` functions. Here's an example of a simple WebSocket echo server:
+Using WebSocket connections in your Next.js app directory is simple with `next-ws`. You can handle WebSocket connections directly in your API routes via exported `UPGRADE` functions.
 
 ```js
-export function SOCKET(
+export function UPGRADE(
   client: import('ws').WebSocket,
-  request: import('http').IncomingMessage,
   server: import('ws').WebSocketServer,
-  context: { params: Record<string, string | string[]> },
+  request: import('next/server').NextRequest,
+  context: import('next-ws/server').RouteContext<'/api/ws'>,
 ) {
   // ...
 }
@@ -70,25 +70,24 @@ export function SOCKET(
 
 ### Echo Server
 
-This example demonstrates a simple WebSocket echo server that sends back any message it receives. Create a new API route file anywhere in your app directory and export a `SOCKET` function to handle WebSocket connections:
+This example demonstrates a simple WebSocket echo server that sends back any message it receives. Create a new API route file anywhere in your app directory and export a `UPGRADE` function to handle WebSocket connections:
 
 ```ts
 // app/api/ws/route.ts (can be any route file in the app directory)
 
-export function SOCKET(
-  client: import("ws").WebSocket,
-  request: import("http").IncomingMessage,
-  server: import("ws").WebSocketServer
+export function UPGRADE(
+  client: import('ws').WebSocket,
+  server: import('ws').WebSocketServer
 ) {
-  console.log("A client connected");
+  console.log('A client connected');
 
-  client.on("message", (message) => {
-    console.log("Received message:", message);
+  client.on('message', (message) => {
+    console.log('Received message:', message);
     client.send(message);
   });
 
-  client.on("close", () => {
-    console.log("A client disconnected");
+  client.once('close', () => {
+    console.log('A client disconnected');
   });
 }
 ```

package/dist/cli.cjs

@@ -27,7 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var import_minimist = __toESM(require("minimist"));
 
 // package.json
-var version = "0.0.0-beta-20250822123253";
+var version = "0.0.0-beta-20250824054249";
 
 // src/commands/helpers/define.ts
 function defineCommandGroup(definition) {

package/dist/server/index.cjs

@@ -39,66 +39,35 @@ __export(server_exports, {
 module.exports = __toCommonJS(server_exports);
 
 // src/server/persistent.ts
-var logger = __toESM(require("next/dist/build/output/log.js"));
-function getEnvironmentMeta() {
-  const isCustomServer = !process.title.startsWith("next-");
-  const isMainProcess = process.env.NEXT_WS_MAIN_PROCESS === "1";
-  const isDevelopment = process.env.NODE_ENV === "development";
-  return { isCustomServer, isMainProcess, isDevelopment };
-}
-function mainProcessOnly(callerName) {
-  if (process.env.NEXT_WS_SKIP_ENVIRONMENT_CHECK === "1") return;
-  const meta = getEnvironmentMeta();
-  if (!meta.isCustomServer && !meta.isMainProcess) {
-    throw new Error(
-      `[next-ws] Attempt to call '${callerName}' outside the main process.
-You may be attempting to interact with the WebSocket server outside of a SOCKET handler. This will fail in production, as Next.js employs a worker process for routing, which do not have access to the WebSocket server on the main process.
-You can resolve this by using a custom server.`
-    );
-  } else if (!meta.isCustomServer) {
-    logger.warnOnce(
-      `[next-ws] The function '${callerName}' was called without a custom server.
-This could lead to unintended behaviour, especially if you're attempting to interact with the WebSocket server outside of a SOCKET handler.
-Please note, while such configurations might function during development, they will fail in production. This is because Next.js employs a worker process for routing in production, which do not have access to the WebSocket server on the main process.
-You can resolve this by using a custom server.`
-    );
-  }
-}
-var kHttpServer = Symbol.for("kHttpServer");
-function getHttpServer() {
-  mainProcessOnly("getHttpServer");
-  return Reflect.get(globalThis, kHttpServer);
-}
-function setHttpServer(server) {
-  mainProcessOnly("setHttpServer");
-  Reflect.set(globalThis, kHttpServer, server);
-  return getHttpServer();
-}
-function useHttpServer(server) {
-  mainProcessOnly("useHttpServer");
-  const existing = getHttpServer();
-  if (existing) return existing;
-  return setHttpServer(server());
-}
-var kWebSocketServer = Symbol.for("kWebSocketServer");
-function getWebSocketServer() {
-  mainProcessOnly("getWebSocketServer");
-  return Reflect.get(globalThis, kWebSocketServer);
-}
-function setWebSocketServer(server) {
-  mainProcessOnly("setWebSocketServer");
-  Reflect.set(globalThis, kWebSocketServer, server);
-  return getWebSocketServer();
-}
-function useWebSocketServer(server) {
-  mainProcessOnly("useWebSocketServer");
-  const existing = getWebSocketServer();
-  if (existing) return existing;
-  return setWebSocketServer(server());
+function useGlobal(key) {
+  return [
+    function get() {
+      return Reflect.get(globalThis, key);
+    },
+    function set(value) {
+      return Reflect.set(globalThis, key, value);
+    },
+    function use(getter) {
+      const existing = Reflect.get(globalThis, key);
+      if (existing) return existing;
+      Reflect.set(globalThis, key, getter());
+      return Reflect.get(globalThis, key);
+    }
+  ];
 }
+var [getHttpServer, setHttpServer, useHttpServer] = (
+  //
+  useGlobal(
+    Symbol.for("next-ws.http-server")
+    //
+  )
+);
+var [getWebSocketServer, setWebSocketServer, useWebSocketServer] = useGlobal(
+  Symbol.for("next-ws.websocket-server")
+);
 
 // src/server/setup.ts
-var logger3 = __toESM(require("next/dist/build/output/log.js"));
+var logger2 = __toESM(require("next/dist/build/output/log.js"));
 var import_ws = require("ws");
 
 // src/server/helpers/match.ts
@@ -142,7 +111,7 @@ function findMatchingRoute(nextServer, requestPathname) {
 }
 
 // src/server/helpers/module.ts
-var logger2 = __toESM(require("next/dist/build/output/log.js"));
+var logger = __toESM(require("next/dist/build/output/log.js"));
 async function importRouteModule(nextServer, filePath) {
   try {
     if ("hotReloader" in nextServer) {
@@ -153,7 +122,7 @@ async function importRouteModule(nextServer, filePath) {
     } else if ("ensurePage" in nextServer) {
       await nextServer.ensurePage({ page: filePath, clientOnly: false });
     } else {
-      logger2.warnOnce(
+      logger.warnOnce(
         "[next-ws] unable to ensure page, you may need to open the route in your browser first so Next.js compiles it"
       );
     }
@@ -168,61 +137,80 @@ async function importRouteModule(nextServer, filePath) {
   }
 }
 
+// src/server/helpers/request.ts
+var import_server = require("next/server");
+function toNextRequest(message) {
+  const controller = new AbortController();
+  const headers = new Headers(message.headers);
+  const protocol = "encrypted" in message.socket ? "https" : "http";
+  const url = `${protocol}://${headers.get("host")}${message.url}`;
+  message.once("aborted", () => controller.abort());
+  return new import_server.NextRequest(url, {
+    method: message.method,
+    headers,
+    body: message.method === "GET" || message.method === "HEAD" ? void 0 : message,
+    signal: controller.signal,
+    referrer: headers.get("referer") || void 0
+  });
+}
+
 // src/server/setup.ts
 function setupWebSocketServer(nextServer) {
-  process.env.NEXT_WS_MAIN_PROCESS = String(1);
-  process.env.NEXT_WS_SKIP_ENVIRONMENT_CHECK = String(1);
   const httpServer = (
     //
     // @ts-expect-error - serverOptions is protected
     useHttpServer(() => nextServer.serverOptions?.httpServer)
   );
   if (!httpServer)
-    return logger3.error("[next-ws] was not able to find the HTTP server");
+    return logger2.error("[next-ws] was not able to find the HTTP server");
   const wsServer = (
     //
     useWebSocketServer(() => new import_ws.WebSocketServer({ noServer: true }))
   );
-  if (!wsServer)
-    return logger3.error("[next-ws] was not able to find the WebSocket server");
-  process.env.NEXT_WS_SKIP_ENVIRONMENT_CHECK = String(0);
-  logger3.ready("[next-ws] has started the WebSocket server");
-  const kInstalled = Symbol.for("kInstalled");
+  logger2.ready("[next-ws] has started the WebSocket server");
+  const kInstalled = Symbol.for("next-ws.http-server.attached");
   if (Reflect.has(httpServer, kInstalled)) return;
   Reflect.set(httpServer, kInstalled, true);
   httpServer.on("upgrade", async (message, socket, head) => {
-    const url = new URL(message.url ?? "", "ws://next");
-    const pathname = url.pathname;
+    const request = toNextRequest(message);
+    const pathname = request.nextUrl.pathname;
     if (pathname.includes("/_next")) return;
     const route = findMatchingRoute(nextServer, pathname);
     if (!route) {
-      logger3.error(`[next-ws] could not find route for page ${pathname}`);
+      logger2.error(`[next-ws] could not find route for page ${pathname}`);
       return socket.end();
     }
     const module2 = await importRouteModule(nextServer, route.filename);
     if (!module2) {
-      logger3.error(`[next-ws] could not import module for page ${pathname}`);
+      logger2.error(`[next-ws] could not import module for page ${pathname}`);
       return socket.end();
     }
+    const handleUpgrade = module2.userland.UPGRADE;
     const handleSocket = module2.userland.SOCKET;
-    if (!handleSocket || typeof handleSocket !== "function") {
-      logger3.error(
-        `[next-ws] route '${pathname}' does not export a valid 'SOCKET' handler`
-      );
+    if ((!handleUpgrade || typeof handleUpgrade !== "function") && (!handleSocket || typeof handleSocket !== "function")) {
+      logger2.error(`[next-ws] route '${pathname}' does not export a handler`);
       return socket.end();
     }
+    if (handleSocket)
+      logger2.warnOnce(
+        "DeprecationWarning: [next-ws] SOCKET is deprecated, use UPGRADE instead, see https://github.com/apteryxxyz/next-ws#-usage"
+      );
     wsServer.handleUpgrade(message, socket, head, async (client) => {
       wsServer.emit("connection", client, message);
       try {
         const context = { params: route.params };
-        const handleClose = (
-          //
-          await handleSocket(client, message, wsServer, context)
-        );
-        if (typeof handleClose === "function")
-          client.once("close", () => handleClose());
+        if (handleUpgrade) {
+          await handleUpgrade(client, wsServer, request, context);
+        } else if (handleSocket) {
+          const handleClose = (
+            //
+            await handleSocket(client, message, wsServer, context)
+          );
+          if (typeof handleClose === "function")
+            client.once("close", () => handleClose());
+        }
       } catch (cause) {
-        logger3.error(
+        logger2.error(
           `[next-ws] error in socket handler for '${pathname}'`,
           cause
         );

package/dist/server/index.d.ts

@@ -1,12 +1,30 @@
-import { Server } from 'node:http';
-import { WebSocketServer } from 'ws';
+import * as next_server from 'next/server';
+import * as http from 'http';
+import * as ws from 'ws';
 import NextNodeServer from 'next/dist/server/next-server.js';
 
-declare function getHttpServer(): Server | undefined;
-declare function setHttpServer<T extends Server | undefined>(server: T): T;
-declare function getWebSocketServer(): WebSocketServer | undefined;
-declare function setWebSocketServer<T extends WebSocketServer | undefined>(server: T): T;
+/** @deprecated Prefer UPGRADE and {@link UpgradeHandler} */
+type SocketHandler = (client: ws.WebSocket, request: http.IncomingMessage, server: ws.WebSocketServer, context: {
+    params: Record<string, string | string[]>;
+}) => unknown;
+type UpgradeHandler = (client: ws.WebSocket, server: ws.WebSocketServer, request: next_server.NextRequest, context: RouteContext<string>) => unknown;
+
+type RouteParams<Path extends string> = Path extends `${infer Before}[[...${infer Param}]]${infer After}` ? RouteParams<Before> & {
+    [K in Param]?: string[];
+} & RouteParams<After> : Path extends `${infer Before}[...${infer Param}]${infer After}` ? RouteParams<Before> & {
+    [K in Param]: string[];
+} & RouteParams<After> : Path extends `${infer Before}[${infer Param}]${infer After}` ? RouteParams<Before> & {
+    [K in Param]: string;
+} & RouteParams<After> : {};
+type RouteContext<Path extends string> = {
+    params: Record<string, string | string[] | undefined> & RouteParams<Path> & RouteParams<Path>;
+};
+
+declare const getHttpServer: () => http.Server<typeof http.IncomingMessage, typeof http.ServerResponse> | undefined;
+declare const setHttpServer: (value: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>) => boolean;
+declare const getWebSocketServer: () => ws.WebSocketServer | undefined;
+declare const setWebSocketServer: (value: ws.WebSocketServer) => boolean;
 
 declare function setupWebSocketServer(nextServer: NextNodeServer): void;
 
-export { getHttpServer, getWebSocketServer, setHttpServer, setWebSocketServer, setupWebSocketServer };
+export { type RouteContext, type SocketHandler, type UpgradeHandler, getHttpServer, getWebSocketServer, setHttpServer, setWebSocketServer, setupWebSocketServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-ws",
-  "version": "0.0.0-beta-20250822123253",
+  "version": "0.0.0-beta-20250824054249",
   "description": "Add support for WebSockets in the Next.js app directory",
   "license": "MIT",
   "keywords": [