next-ws 0.1.5-next.78595a2 → 0.2.0

package/README.md

@@ -21,6 +21,8 @@ Next WS (`next-ws`) is an advanced Next.js **13** plugin designed to seamlessly
 
 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.
 
 ---
@@ -30,36 +32,37 @@ This module is inspired by the now outdated `next-plugin-websocket`, if you are
 - [🤔 About](#-about)
 - [🏓 Table of Contents](#-table-of-contents)
 - [📦 Installation](#-installation)
-- [🚀 Usage](#-api)
+- [🚀 Usage](#-usage)
+    - [🚓 Verify Patch](#-verify-patch)
 - [🌀 Example](#-example)
-  - [📁 Server](#-server)
-  - [📁 Client](#-client)
-  
+    - [📁 Server](#-server)
+    - [📁 Client](#-client)
+
 ---
 
 ## 📦 Installation
 
+In order to setup a WebSocket server, Next WS needs to patch your local Next.js installation. Next WS provides a CLI command to do this for you, it will automatically detect your Next.js version and patch it accordingly, however a minimum version of Next.js 13.1.1 is required.
+
 ```sh
-npm install next-ws
-yarn add next-ws
-pnpm add next-ws
+npx next-ws-cli patch
 ```
 
-Upon installation, Next WS will automatically patch your existing Next.js installation to add support for WebSockets in API routes in the app directory. 
+> If at any point your local Next.js installation is changed or updated you will need to re-run the patch command.
 
-<details>
-    <summary><strong>Caveats</strong></summary>
+Once the patch is complete, you will need to install the Next WS package into your project.
 
-As this module modifies the Next.js installation, if for any reason it changes (such as when you update Next.js), you will need to reinstall Next WS. And if you want to uninstall Next WS, you will need to reinstall Next.js.
-</details>
+```sh
+npm install next-ws
+```
 
 ---
 
 ## 🚀 Usage
 
-Using Next WS is a breeze, requiring zero configuration. Simply export a `SOCKET` function from an API route. This function gets called whenever a client connects to the WebSocket server at the respective API path.
+Using Next WS is a breeze, requiring zero configuration. Simply export a `SOCKET` function from any API route. This function gets called whenever a client connects to the WebSocket server at the respective API path.
 
-The `SOCKET` function receives two arguments: the WebSocket client and the HTTP request, which you can use to get the URL path, query parameters, and headers.
+The `SOCKET` function receives three arguments: the WebSocket client, the HTTP request - which you can use to get the URL path, query parameters, and headers - and the WebSocket server that `next-ws` created.
 
 ```ts
 export function SOCKET(
@@ -73,6 +76,16 @@ export function SOCKET(
 
 With this straightforward setup, you can fully leverage the capabilities of Next WS and efficiently handle WebSocket connections within your Next.js application.
 
+### 🚓 Verify Patch
+
+It is recommended to add the following code to the top level of your `next.config.js`.
+
+This will verify that Next WS has been patched correctly, and throw an error if it has not. Preventing you from accidentally deploying a broken setup.
+
+```ts
+require('next-ws/server').verifyPatch();
+```
+
 ---
 
 ## 🌀 Example
@@ -86,6 +99,7 @@ Create an API route anywhere within the app directory, and export a `SOCKET` fun
 export function SOCKET(
     client: import('ws').WebSocket,
     request: import('http').IncomingMessage,
+    server: import('ws').WebSocketServer,
 ) {
     console.log('A client connected!');
 
@@ -101,11 +115,9 @@ export function SOCKET(
 
 You are pretty much done at this point, you can now connect to the WebSocket server using the native WebSocket API in the browser.
 
----
-
 ### 📁 Client
 
-To make it easier to connect to your new WebSocker server, Next WS also provides some client-side utilities. These are not required, you can use the native WebSocket API if you prefer.
+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.
 
 ```tsx
 // layout.tsx
@@ -114,12 +126,45 @@ To make it easier to connect to your new WebSocker server, Next WS also provides
 import { WebSocketProvider } from 'next-ws/client';
 
 export default function Layout() {
-    return <WebSocketProvider url="ws://localhost:3000/api/ws">
+    return <WebSocketProvider
+        url="ws://localhost:3000/api/ws"
+        // ... other props
+    >
         {...}
     </WebSocketProvider>;
 }
 ```
 
+The following is the props interface for the `WebSocketProvider` component, containing all the available options.
+
+```ts
+interface WebSocketProviderProps {
+    children: React.ReactNode;
+
+    /** The URL for the WebSocket to connect to. */
+    url: string;
+    /** The subprotocols to use. */
+    protocols?: string[] | string;
+    /** The binary type to use. */
+    binaryType?: BinaryType;
+
+    /** Whether to reconnect when the WebSocket closes. */
+    reconnect?: boolean;
+    /** The maximum number of times to reconnect. */
+    maxReconnectAttempts?: number;
+    /** The delay between reconnect attempts. */
+    reconnectDelay?: number;
+
+    // NOTE: You do not need to use these, they are only here for convenience
+    /** Event listener that is triggered when the WebSocket connection opens. */
+    onOpen?(this: WebSocket, event: Event): any;
+    /** Event listener that is triggered when the WebSocket connection closes. */
+    onClose?(this: WebSocket, event: CloseEvent): any;
+    /** Event listener that is triggered when an error occurs. */
+    onError?(this: WebSocket, event: Event): any;
+}
+```
+
 ```tsx
 // page.tsx
 'use client';
@@ -129,7 +174,8 @@ import { useCallback, useEffect, useState } from 'react';
 
 export default function Page() {
     const ws = useWebSocket();
-    //    ^? WebSocket on the client, null on the server
+    // WebSocket instance only exists when connected
+    // It will be null when state is closed or connecting
 
     const [value, setValue] = useState('');
     const [message, setMessage] = useState<string | null>('');
@@ -142,7 +188,7 @@ export default function Page() {
     useEffect(() => {
         ws?.addEventListener('message', onMessage);
         return () => ws?.removeEventListener('message', onMessage);
-    }, []);
+    }, [ws]);
 
     return <>
         <input
@@ -160,6 +206,6 @@ export default function Page() {
                 ? 'Waiting for server to send a message...'
                 : `Got message: ${message}`}
         </p>
-    </>
+    </>;
 }
 ```

package/client/context.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="react" />
+export declare const WebSocketContext: import("react").Context<WebSocket | null>;
+export interface WebSocketProviderProps {
+    children: React.ReactNode;
+    /** The URL for the WebSocket to connect to. */
+    url: string;
+    /** The subprotocols to use. */
+    protocols?: string[] | string;
+    /** The binary type to use. */
+    binaryType?: BinaryType;
+}
+/**
+ * Provides a WebSocket instance to its children via context,
+ * allowing for easy access to the WebSocket from anywhere in the app.
+ * @param props WebSocket parameters and children.
+ * @returns JSX Element
+ */
+export declare function WebSocketProvider({ children, url, protocols, binaryType, }: WebSocketProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare const WebSocketConsumer: import("react").Consumer<WebSocket | null>;
+/**
+ * Access the websocket from anywhere in the app, so long as it's wrapped in a WebSocketProvider.
+ * @returns WebSocket instance when connected, null when disconnected.
+ */
+export declare function useWebSocket(): WebSocket | null;

package/client/context.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWebSocket = exports.WebSocketConsumer = exports.WebSocketProvider = exports.WebSocketContext = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+exports.WebSocketContext = (0, react_1.createContext)(null);
+exports.WebSocketContext.displayName = 'WebSocketContext';
+/**
+ * Provides a WebSocket instance to its children via context,
+ * allowing for easy access to the WebSocket from anywhere in the app.
+ * @param props WebSocket parameters and children.
+ * @returns JSX Element
+ */
+function WebSocketProvider({ children, url, protocols, binaryType, }) {
+    const isBrowser = typeof window !== 'undefined';
+    const setupClient = () => {
+        if (!isBrowser)
+            return null;
+        const client = new WebSocket(url, protocols);
+        if (binaryType)
+            client.binaryType = binaryType;
+        return client;
+    };
+    const instance = (0, react_1.useMemo)(setupClient, [isBrowser, url, protocols]);
+    (0, react_1.useEffect)(() => {
+        return () => instance?.close();
+    }, []);
+    return (0, jsx_runtime_1.jsx)(exports.WebSocketContext.Provider, { value: instance, children: children });
+}
+exports.WebSocketProvider = WebSocketProvider;
+exports.WebSocketConsumer = exports.WebSocketContext.Consumer;
+/**
+ * Access the websocket from anywhere in the app, so long as it's wrapped in a WebSocketProvider.
+ * @returns WebSocket instance when connected, null when disconnected.
+ */
+function useWebSocket() {
+    const context = (0, react_1.useContext)(exports.WebSocketContext);
+    if (context === undefined)
+        throw new Error('useWebSocket must be used within a WebSocketProvider');
+    return context;
+}
+exports.useWebSocket = useWebSocket;

package/client/index.d.ts

@@ -0,0 +1 @@
+export * from './context';

package/client/index.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./context"), exports);

package/index.d.ts

@@ -0,0 +1 @@
+export {};

package/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+throw new Error("next-ws cannot be directory imported, use 'next-ws/server' or 'next-ws/client' instead");

package/package.json

@@ -1,75 +1,46 @@
 {
     "name": "next-ws",
-    "version": "0.1.5-next.78595a2",
+    "version": "0.2.0",
     "description": "Add support for WebSockets in Next.js 13 app directory",
-    "packageManager": "yarn@3.6.0",
+    "keywords": ["next", "websocket", "ws", "server", "client"],
     "license": "MIT",
-    "keywords": [
-        "next",
-        "websocket",
-        "ws",
-        "server",
-        "client"
-    ],
     "homepage": "https://github.com/apteryxxyz/next-ws#readme",
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/apteryxxyz/next-ws.git"
+        "url": "git+https://github.com/apteryxxyz/next-ws.git",
+        "directory": "packages/core"
     },
     "bugs": {
         "url": "https://github.com/apteryxxyz/next-ws/issues"
     },
-    "files": [
-        "*.js",
-        "*.d.ts"
-    ],
+    "files": ["index.js", "index.d.ts", "client", "server"],
+    "main": "./index.js",
+    "types": "./index.d.ts",
     "scripts": {
-        "build": "tsc",
-        "clean": "rimraf client server common",
+        "build": "cp ../../README.md . && tsc",
+        "clean": "rimraf index.js index.d.ts client server README.md",
         "lint": "eslint --ext .ts,.tsx src",
-        "format": "prettier --write src/**/*.{ts,tsx} && eslint --fix --ext .ts,.tsx src/",
-        "postinstall": "node -e \"try{require('./common/patch.js')}catch{}\""
+        "format": "prettier --write src/**/*.{ts,tsx} && eslint --fix --ext .ts,.tsx src/"
     },
     "dependencies": {
-        "@babel/generator": "^7.22.5",
-        "@babel/parser": "^7.22.5",
-        "@babel/template": "^7.22.5"
+        "ws": "^8.13.0"
     },
     "peerDependencies": {
-        "next": "*",
-        "react": "*",
-        "ws": "*"
+        "next": ">=13.1.1",
+        "react": "*"
     },
     "devDependencies": {
-        "@babel/types": "^7.22.4",
-        "@rushstack/eslint-patch": "^1.3.0",
-        "@types/babel__generator": "^7",
-        "@types/babel__template": "^7",
         "@types/eslint": "^8",
-        "@types/node": "^20.2.5",
         "@types/prettier": "^2",
         "@types/react": "^18",
+        "@types/react-dom": "^18",
         "@types/ws": "^8",
-        "@typescript-eslint/eslint-plugin": "^5.59.8",
-        "@typescript-eslint/parser": "^5.59.8",
-        "eslint": "^8.41.0",
-        "eslint-config-apteryx": "^2.1.7",
-        "eslint-config-prettier": "^8.8.0",
-        "eslint-plugin-import": "^2.27.5",
-        "eslint-plugin-jsdoc": "^46.1.0",
-        "eslint-plugin-n": "^16.0.0",
-        "eslint-plugin-prettier": "^4.2.1",
-        "eslint-plugin-promise": "^6.1.1",
-        "eslint-plugin-sonarjs": "^0.19.0",
-        "eslint-plugin-unicorn": "^47.0.0",
-        "next": "^13.4.4",
+        "eslint": "^8.43.0",
+        "next": "^13.4.6",
         "prettier": "^2.8.8",
-        "prettier-config-apteryx": "^2.1.0",
         "react": "^18.2.0",
+        "react-dom": "^18.2.0",
         "rimraf": "^5.0.1",
-        "ts-config-apteryx": "^2.1.0",
-        "typescript": "<5.1.0",
-        "ws": "^8.13.0"
-    },
-    "prettier": "prettier-config-apteryx"
-}
+        "typescript": "<5.1.0"
+    }
+}

package/server/index.d.ts

@@ -0,0 +1,3 @@
+export * from './utilities/patch';
+export type { SocketHandler } from './utilities/next';
+export * from './setup';

package/server/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./utilities/patch"), exports);
+tslib_1.__exportStar(require("./setup"), exports);

package/server/setup.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hookNextNodeServer = exports.setupWebSocketServer = void 0;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const Log = tslib_1.__importStar(require("next/dist/build/output/log"));
+const ws_1 = require("ws");
+const next_1 = require("./utilities/next");
+function setupWebSocketServer(nextServer) {
+    const httpServer = (0, next_1.getHttpServer)(nextServer);
+    const wsServer = new ws_1.WebSocketServer({ noServer: true });
+    Log.ready('[next-ws] websocket server started successfully');
+    httpServer.on('upgrade', async (request, socket, head) => {
+        const url = new URL(request.url ?? '', 'http://next-ws');
+        const pathname = await (0, next_1.resolvePathname)(nextServer, url.pathname);
+        if (!pathname)
+            return;
+        const fsPathname = node_path_1.default
+            .join(pathname, 'route')
+            .replaceAll(node_path_1.default.sep, '/');
+        const pageModule = await (0, next_1.getPageModule)(nextServer, fsPathname);
+        if (!pageModule)
+            return Log.error(`[next-ws] could not find module for page ${pathname}`);
+        const socketHandler = pageModule?.routeModule?.userland?.SOCKET;
+        if (!socketHandler || typeof socketHandler !== 'function')
+            return Log.error(`[next-ws] could not find SOCKET handler for page ${pathname}`);
+        wsServer.handleUpgrade(request, socket, head, (client, request) => {
+            socketHandler(client, request, wsServer);
+        });
+    });
+}
+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() {
+    setupWebSocketServer(this);
+}
+exports.hookNextNodeServer = hookNextNodeServer;

package/server/utilities/next.d.ts

@@ -0,0 +1,31 @@
+/// <reference types="node" />
+import { Server } from 'node:http';
+import NextNodeServer from 'next/dist/server/next-server';
+/** 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) => any;
+/**
+ * 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.
+ * @param nextServer The NextNodeServer instance.
+ * @param pathname The pathname to resolve.
+ * @returns The resolved page, or null if the page could not be resolved.
+ */
+export declare function resolvePathname(nextServer: NextNodeServer, pathname: string): Promise<string | null>;
+/**
+ * Get the page module for a page.
+ * @param nextServer The NextNodeServer instance.
+ * @param filename The filename of the page.
+ * @returns The page module.
+ */
+export declare function getPageModule(nextServer: NextNodeServer, filename: string): Promise<any>;

package/server/utilities/next.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPageModule = exports.resolvePathname = exports.getHttpServer = 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 is_dynamic_1 = require("next/dist/shared/lib/router/utils/is-dynamic");
+/**
+ * Get the http.Server instance from the NextNodeServer.
+ * @param nextServer The NextNodeServer instance.
+ * @returns The http.Server instance.
+ */
+// prettier-ignore
+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.
+ * @param nextServer The NextNodeServer instance.
+ * @param pathname The pathname to resolve.
+ * @returns The resolved page, or null if the page could not be resolved.
+ */
+async function resolvePathname(nextServer, pathname) {
+    if (pathname.startsWith('/_next'))
+        return null;
+    // @ts-expect-error hasPage is protected
+    if (!(0, is_dynamic_1.isDynamicRoute)(pathname) && (await nextServer.hasPage(pathname)))
+        return pathname;
+    // @ts-expect-error dynamicRoutes is protected
+    for (const route of nextServer.dynamicRoutes ?? []) {
+        const params = route.match(pathname) || undefined;
+        if (params)
+            return route.page;
+    }
+    return null;
+}
+exports.resolvePathname = resolvePathname;
+/**
+ * Get the page module for a page.
+ * @param nextServer The NextNodeServer instance.
+ * @param filename The filename of the page.
+ * @returns The page module.
+ */
+async function getPageModule(nextServer, filename) {
+    // @ts-expect-error HotReloader is private
+    await nextServer.hotReloader.ensurePage({
+        page: filename,
+        clientOnly: false,
+    });
+    // @ts-expect-error getPagePath is protected
+    const builtPagePath = nextServer.getPagePath(filename);
+    return require(builtPagePath);
+}
+exports.getPageModule = getPageModule;

package/server/utilities/patch.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Get the Next WS patch version and Next.js version.
+ * @returns The patch version and Next.js version if the patch has been applied, otherwise null.
+ */
+export declare function getPatch(): {
+    patch: string;
+    version: string;
+} | null;
+/**
+ * Verify that the Next WS patch has been applied to Next.js.
+ * @returns The patch version and Next.js version if the patch has been applied, otherwise null.
+ */
+export declare function verifyPatch(): void;

package/server/utilities/patch.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyPatch = exports.getPatch = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+const workspace_1 = require("./workspace");
+/**
+ * Get the Next WS patch version and Next.js version.
+ * @returns The patch version and Next.js version if the patch has been applied, otherwise null.
+ */
+function getPatch() {
+    const location = path.join((0, workspace_1.findWorkspaceRoot)(), 'node_modules/next/.next-ws-trace.json');
+    try {
+        const content = fs.readFileSync(location, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+exports.getPatch = getPatch;
+/**
+ * Verify that the Next WS patch has been applied to Next.js.
+ * @returns The patch version and Next.js version if the patch has been applied, otherwise null.
+ */
+// prettier-ignore
+function verifyPatch() {
+    const patch = getPatch();
+    if (!patch)
+        throw new Error('Next.js has not been patched to support Next WS, please run `npx next-ws-cli patch`');
+    const version = require('next/package.json').version.split('-')[0];
+    if (patch.version !== version)
+        throw new Error(`Next.js version mismatch, expected ${patch.version} but found ${version}`);
+}
+exports.verifyPatch = verifyPatch;

package/server/utilities/workspace.d.ts

@@ -0,0 +1 @@
+export declare function findWorkspaceRoot(initalPath?: string): string;

package/server/utilities/workspace.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findWorkspaceRoot = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+function findWorkspaceRoot(initalPath = process.cwd()) {
+    let currentPath = initalPath;
+    let lastPossiblePath = currentPath;
+    let isRoot = 'maybe';
+    const isCurrentPathRoot = () => {
+        const files = fs.readdirSync(currentPath);
+        const lockFiles = ['pnpm-lock.yaml', 'yarn.lock', 'package-lock.json'];
+        const hasLockFile = files.some(file => lockFiles.includes(file));
+        if (hasLockFile)
+            return 'true';
+        const packageJson = files.find(file => file === 'package.json');
+        if (packageJson) {
+            const packageContent = fs.readFileSync(path.resolve(currentPath, packageJson), 'utf8');
+            const packageObject = JSON.parse(packageContent);
+            if (packageObject.packageManager)
+                return 'true';
+            return 'maybe';
+        }
+        return 'false';
+    };
+    while (true) {
+        isRoot = isCurrentPathRoot();
+        const nextPath = path.resolve(currentPath, '..');
+        if (isRoot === 'true' || nextPath === currentPath)
+            break;
+        else if (isRoot === 'maybe')
+            lastPossiblePath = currentPath;
+        currentPath = nextPath;
+    }
+    return isRoot === 'true' ? currentPath : lastPossiblePath;
+}
+exports.findWorkspaceRoot = findWorkspaceRoot;