next-ws 0.2.7 → 1.0.1-canary.1

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <h1><strong>Next WS</strong></h1>
-  <i>Add support for WebSockets in Next.js 13 app directory</i><br>
+  <i>Add support for WebSockets in Next.js app directory</i><br>
   <code>npm install next-ws ws</code>
 </div>
 
@@ -17,14 +17,10 @@
 
 ## 🤔 About
 
-Next WS (`next-ws`) is an advanced Next.js **13** plugin designed to seamlessly integrate WebSocket server functionality into API routes within the **app directory**. With Next WS, you no longer require a separate server for WebSocket functionality.
-
-> The last supported version of Next.js is 13.4.12, read more [here](https://github.com/apteryxxyz/next-ws/issues/6). 
+Next WS (`next-ws`) is an advanced Next.js plugin designed to seamlessly integrate WebSocket server functionality into API routes within the **app directory**. With Next WS, you no longer require a separate server for WebSocket functionality.
 
 It's **important** to note that this module can only be used when working with a server. Unfortunately, in serverless environments like Vercel, WebSocket servers cannot be used. Additionally, this module was built for the app directory and is incompatible with the older pages directory.
 
-Next WS is still pre its 1.0 release, and as such, things may change. If you find any bugs or have any suggestions, please open an issue on the GitHub repository.
-
 This module is inspired by the now outdated `next-plugin-websocket`, if you are using an older version of Next.js, that module may work for you.
 
 ---
@@ -138,8 +134,6 @@ export default function Layout() {
 }
 ```
 
-To make it easier to connect to your new WebSocker server, Next WS also provides some client-side utilities. These are completely optional, you can use your own implementation if you wish.
-
 The following is the props interface for the `WebSocketProvider` component, containing all the available options.
 
 ```ts
@@ -155,6 +149,8 @@ interface WebSocketProviderProps {
 }
 ```
 
+Now you can use the `useWebSocket` hook to get the WebSocket instance, and send and receive messages.
+
 ```tsx
 // page.tsx
 'use client';

package/client/context.js

@@ -26,7 +26,7 @@ function WebSocketProvider({ children, url, protocols, binaryType, }) {
             return;
         return () => instance.close();
     }, []);
-    return (0, jsx_runtime_1.jsx)(exports.WebSocketContext.Provider, { value: instance, children: children });
+    return ((0, jsx_runtime_1.jsx)(exports.WebSocketContext.Provider, { value: instance, children: children }));
 }
 exports.WebSocketProvider = WebSocketProvider;
 exports.WebSocketConsumer = exports.WebSocketContext.Consumer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-ws",
-  "version": "0.2.7",
+  "version": "1.0.1-canary.1",
   "description": "Add support for WebSockets in Next.js 13 app directory",
   "keywords": [
     "next",
@@ -43,12 +43,13 @@
     "@types/react-dom": "^18",
     "@types/ws": "^8",
     "eslint": "^8.43.0",
-    "next": "^13.4.6",
+    "next": "^14.0.1",
     "prettier": "^2.8.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,33 +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 next_server_1 = tslib_1.__importDefault(require("next/dist/server/next-server"));
+const Log = tslib_1.__importStar(require("next/dist/build/output/log"));
 /**
- * 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
@@ -74,12 +58,28 @@ exports.resolvePathname = resolvePathname;
  * @returns The page module.
  */
 async function getPageModule(nextServer, filename) {
-    // @ts-expect-error - hotReloader is private
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
-    await nextServer.hotReloader?.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');
+            }
+        }
+        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');
+        }
+    }
     // @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,49 @@
+"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) {
+    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;
+    }
+    if (!nextServer || !(nextServer instanceof next_server_1.default)) {
+        Log.error('[next-ws] could not find the NextNodeServer instance');
+        process.exit(1);
+    }
+    // @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;