next-ws 1.0.0 → 1.0.1-experimental.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-ws",
-  "version": "1.0.0",
+  "version": "1.0.1-experimental.1",
   "description": "Add support for WebSockets in Next.js 13 app directory",
   "keywords": [
     "next",
@@ -48,7 +48,8 @@
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "rimraf": "^5.0.1",
-    "typescript": "<5.1.0"
+    "typescript": "<5.1.0",
+    "ws": "^8.14.2"
   },
   "eslintConfig": {
     "root": true,

package/server/index.d.ts

@@ -1,3 +1,3 @@
-export * from './utilities/patch';
-export type { SocketHandler } from './utilities/ws';
 export * from './setup';
+export * from './utilities/patch';
+export { SocketHandler, CustomHttpServer, CustomWsServer, } from './utilities/server';

package/server/index.js

@@ -1,5 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomWsServer = exports.CustomHttpServer = void 0;
 const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./utilities/patch"), exports);
 tslib_1.__exportStar(require("./setup"), exports);
+tslib_1.__exportStar(require("./utilities/patch"), exports);
+var server_1 = require("./utilities/server");
+Object.defineProperty(exports, "CustomHttpServer", { enumerable: true, get: function () { return server_1.CustomHttpServer; } });
+Object.defineProperty(exports, "CustomWsServer", { enumerable: true, get: function () { return server_1.CustomWsServer; } });

package/server/setup.d.ts

@@ -1,3 +1,3 @@
-import type NextNodeServer from 'next/dist/server/next-server';
+import NextNodeServer from 'next/dist/server/next-server';
 export declare function setupWebSocketServer(nextServer: NextNodeServer): void;
 export declare function hookNextNodeServer(this: NextNodeServer): void;

package/server/setup.js

@@ -4,31 +4,34 @@ exports.hookNextNodeServer = exports.setupWebSocketServer = void 0;
 const tslib_1 = require("tslib");
 const Log = tslib_1.__importStar(require("next/dist/build/output/log"));
 const next_1 = require("./utilities/next");
-const ws_1 = require("./utilities/ws");
+const server_1 = require("./utilities/server");
 function setupWebSocketServer(nextServer) {
-    const httpServer = (0, next_1.getHttpServer)(nextServer);
-    const wsServer = (0, ws_1.getWsServer)();
-    Log.ready('[next-ws] websocket server started successfully');
+    const httpServer = (0, server_1.useHttpServer)(nextServer);
+    const wsServer = (0, server_1.useWsServer)();
+    Log.ready('[next-ws] has started the WebSocket server');
     // eslint-disable-next-line @typescript-eslint/no-misused-promises
     httpServer.on('upgrade', async (request, socket, head) => {
         const url = new URL(request.url ?? '', 'ws://next');
         const pathname = url.pathname;
+        // Ignore Next.js internal requests (aka HMR)
         if (pathname.startsWith('/_next'))
             return;
+        // Resolve the pathname to a file system path (eg /about -> /about/route)
         const fsPathname = (0, next_1.resolvePathname)(nextServer, pathname);
         if (!fsPathname) {
-            Log.error(`[next-ws] could not find module for page ${pathname}`);
-            return socket.destroy();
+            Log.error('[next-ws] could not resolve ${pathname} to a route');
+            return socket.end();
         }
+        // Get the page module for the pathname (aka require('/about/route'))
         const pageModule = await (0, next_1.getPageModule)(nextServer, fsPathname);
         if (!pageModule) {
-            Log.error(`[next-ws] could not find module for page ${pathname}`);
-            return socket.destroy();
+            Log.error('[next-ws] could not find module for page ${pathname}');
+            return socket.end();
         }
         const socketHandler = pageModule?.routeModule?.userland?.SOCKET;
         if (!socketHandler || typeof socketHandler !== 'function') {
-            Log.error(`[next-ws] ${pathname} does not export a SOCKET handler`);
-            return socket.destroy();
+            Log.error('[next-ws] ${pathname} does not export a SOCKET handler');
+            return socket.end();
         }
         return wsServer.handleUpgrade(request, socket, head, (client, request) => void socketHandler(client, request, wsServer));
     });
@@ -37,6 +40,7 @@ exports.setupWebSocketServer = setupWebSocketServer;
 // Next WS versions below 0.2.0 used a different method of setup
 // This remains for backwards compatibility, but may be removed in a future version
 function hookNextNodeServer() {
+    Log.warnOnce('[next-ws] is using a deprecated method of hooking into Next.js, this may break in future versions');
     setupWebSocketServer(this);
 }
 exports.hookNextNodeServer = hookNextNodeServer;

package/server/utilities/next.d.ts

@@ -1,15 +1,8 @@
-/// <reference types="node" />
-import { Server } from 'node:http';
 import NextNodeServer from 'next/dist/server/next-server';
-import type { SocketHandler } from './ws';
 /**
- * Get the http.Server instance from the NextNodeServer.
- * @param nextServer The NextNodeServer instance.
- * @returns The http.Server instance.
- */
-export declare function getHttpServer(nextServer: NextNodeServer): Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
-/**
- * Resolve a pathname to a page.
+ * Resolve a pathname to a page, or null if the page could not be resolved.
+ * @example resolvePathname(nextServer, '/about') // '/about/route'
+ * @example resolvePathname(nextServer, '/user/1') // '/user/[id]/route'
  * @param nextServer The NextNodeServer instance.
  * @param pathname The pathname to resolve.
  * @returns The resolved page, or null if the page could not be resolved.
@@ -25,7 +18,7 @@ export declare function getPageModule(nextServer: NextNodeServer, filename: stri
 export interface PageModule {
     routeModule?: {
         userland?: {
-            SOCKET?: SocketHandler;
+            SOCKET?: unknown;
         };
     };
 }

package/server/utilities/next.js

@@ -1,34 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPageModule = exports.resolvePathname = exports.getHttpServer = void 0;
+exports.getPageModule = exports.resolvePathname = void 0;
 const tslib_1 = require("tslib");
-const node_http_1 = require("node:http");
 const Log = tslib_1.__importStar(require("next/dist/build/output/log"));
-const next_server_1 = tslib_1.__importDefault(require("next/dist/server/next-server"));
 /**
- * Get the http.Server instance from the NextNodeServer.
- * @param nextServer The NextNodeServer instance.
- * @returns The http.Server instance.
- */
-function getHttpServer(nextServer) {
-    if (!nextServer || !(nextServer instanceof next_server_1.default))
-        throw new Error('Next WS is missing access to the NextNodeServer');
-    // @ts-expect-error - serverOptions is protected
-    const httpServer = nextServer.serverOptions?.httpServer;
-    if (!httpServer || !(httpServer instanceof node_http_1.Server))
-        throw new Error('Next WS is missing access to the http.Server');
-    return httpServer;
-}
-exports.getHttpServer = getHttpServer;
-/**
- * Resolve a pathname to a page.
+ * Resolve a pathname to a page, or null if the page could not be resolved.
+ * @example resolvePathname(nextServer, '/about') // '/about/route'
+ * @example resolvePathname(nextServer, '/user/1') // '/user/[id]/route'
  * @param nextServer The NextNodeServer instance.
  * @param pathname The pathname to resolve.
  * @returns The resolved page, or null if the page could not be resolved.
  */
 function resolvePathname(nextServer, pathname) {
-    if (pathname.startsWith('/_next'))
-        return null;
     const pathParts = pathname.split('/');
     const appRoutes = {
         // @ts-expect-error - appPathRoutes is protected
@@ -75,29 +58,28 @@ exports.resolvePathname = resolvePathname;
  * @returns The page module.
  */
 async function getPageModule(nextServer, filename) {
-    try {
-        // In Next.js 14, hotReloader was removed and ensurePage was moved to NextNodeServer
-        if ('hotReloader' in nextServer) {
-            // @ts-expect-error - hotReloader only exists in Next.js 13
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-            await nextServer.hotReloader?.ensurePage({
-                page: filename,
-                clientOnly: false,
-            });
-        }
-        else if ('ensurePage' in nextServer) {
-            // ensurePage throws an error in production, so we need to catch it
-            // @ts-expect-error - ensurePage is protected
-            await nextServer.ensurePage({ page: filename, clientOnly: false });
+    if (process.env['NODE_ENV'] !== 'production') {
+        try {
+            if ('hotReloader' in nextServer) {
+                // @ts-expect-error - hotReloader only exists in Next.js 13
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+                await nextServer.hotReloader.ensurePage({
+                    page: filename,
+                    clientOnly: false,
+                });
+            }
+            else if ('ensurePage' in nextServer) {
+                // @ts-expect-error - ensurePage is protected
+                await nextServer.ensurePage({ page: filename, clientOnly: false });
+            }
+            else {
+                Log.warnOnce('[next-ws] cannot find a way to ensure page, you may need to open routes in your browser first so Next.js compiles them');
+            }
         }
-        else {
-            // Future-proofing
-            Log.warnOnce('[next-ws] was unable to ensure page, you may need to open the route in your browser first so Next.js compiles it');
+        catch (error) {
+            Log.error('[next-ws] was unable to ensure page, you may need to open the route in your browser first so Next.js compiles it');
         }
     }
-    catch {
-        void 0;
-    }
     // @ts-expect-error - getPagePath is protected
     const builtPagePath = nextServer.getPagePath(filename);
     // eslint-disable-next-line @typescript-eslint/no-var-requires

package/server/utilities/server.d.ts

@@ -0,0 +1,33 @@
+/// <reference types="node" />
+import { Server } from 'node:http';
+import NextNodeServer from 'next/dist/server/next-server';
+import { WebSocketServer } from 'ws';
+export declare const CustomHttpServer: unique symbol;
+/**
+ * Get the HTTP Server instance from the NextNodeServer.
+ * @param nextServer The NextNodeServer instance.
+ * @returns The HTTP Server instance.
+ */
+export declare function useHttpServer(nextServer: NextNodeServer): Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
+export declare const CustomWsServer: unique symbol;
+/**
+ * Create a WebSocketServer.
+ * @returns The WebSocketServer instance.
+ */
+export declare function useWsServer(): WebSocketServer;
+/** A function that handles a WebSocket connection. */
+export type SocketHandler = (
+/** The WebSocket client that connected. */
+client: import('ws').WebSocket, 
+/** The HTTP request that initiated the WebSocket connection. */
+request: import('http').IncomingMessage, 
+/** The WebSocket server. */
+server: import('ws').WebSocketServer) => unknown;
+declare global {
+    export namespace NodeJS {
+        interface Global {
+            [CustomHttpServer]: import('node:http').Server;
+            [CustomWsServer]: import('ws').WebSocketServer;
+        }
+    }
+}

package/server/utilities/server.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWsServer = exports.CustomWsServer = exports.useHttpServer = exports.CustomHttpServer = void 0;
+const tslib_1 = require("tslib");
+const node_http_1 = require("node:http");
+const Log = tslib_1.__importStar(require("next/dist/build/output/log"));
+const next_server_1 = tslib_1.__importDefault(require("next/dist/server/next-server"));
+const ws_1 = require("ws");
+// =============== HTTP Server ===============
+exports.CustomHttpServer = Symbol('NextWS::CustomHttpServer');
+/**
+ * Get the HTTP Server instance from the NextNodeServer.
+ * @param nextServer The NextNodeServer instance.
+ * @returns The HTTP Server instance.
+ */
+function useHttpServer(nextServer) {
+    // NextNodeServer is always required, so check for it before attempting to use custom server
+    if (!nextServer || !(nextServer instanceof next_server_1.default)) {
+        Log.error('[next-ws] could not find the NextNodeServer instance');
+        process.exit(1);
+    }
+    const existing = Reflect.get(globalThis, exports.CustomHttpServer);
+    if (existing) {
+        Log.warnOnce('[next-ws] is using a custom HTTP Server, this is experimental and may not work as expected');
+        return existing;
+    }
+    // @ts-expect-error - serverOptions is protected
+    const httpServer = nextServer.serverOptions?.httpServer;
+    if (!httpServer || !(httpServer instanceof node_http_1.Server)) {
+        Log.error('[next-ws] could not find the HTTP Server instance');
+        process.exit(1);
+    }
+    return httpServer;
+}
+exports.useHttpServer = useHttpServer;
+// =============== WebSocket Server ===============
+exports.CustomWsServer = Symbol('NextWS::CustomWsServer');
+/**
+ * Create a WebSocketServer.
+ * @returns The WebSocketServer instance.
+ */
+function useWsServer() {
+    const existing = Reflect.get(globalThis, exports.CustomWsServer);
+    if (existing) {
+        Log.warnOnce('[next-ws] is using a custom WebSocketServer, this is experimental and may not work as expected');
+        return existing;
+    }
+    return new ws_1.WebSocketServer({ noServer: true });
+}
+exports.useWsServer = useWsServer;

package/server/utilities/ws.d.ts

@@ -1,15 +0,0 @@
-/// <reference types="ws" />
-/// <reference types="node" />
-/** A function that handles a WebSocket connection. */
-export type SocketHandler = (
-/** The WebSocket client that connected. */
-client: import('ws').WebSocket, 
-/** The HTTP request that initiated the WebSocket connection. */
-request: import('http').IncomingMessage, 
-/** The WebSocket server. */
-server: import('ws').WebSocketServer) => unknown;
-/**
- * Get the WebSocketServer instance.
- * @returns The WebSocketServer instance.
- */
-export declare function getWsServer(): import("ws").Server<typeof import("ws"), typeof import("http").IncomingMessage>;

package/server/utilities/ws.js

@@ -1,13 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getWsServer = void 0;
-/* eslint-disable @typescript-eslint/consistent-type-imports */
-const ws_1 = require("ws");
-/**
- * Get the WebSocketServer instance.
- * @returns The WebSocketServer instance.
- */
-function getWsServer() {
-    return new ws_1.WebSocketServer({ noServer: true });
-}
-exports.getWsServer = getWsServer;