next-ws 1.0.1 → 1.1.0-next.2

package/package.json

@@ -1,15 +1,10 @@
 {
   "name": "next-ws",
-  "version": "1.0.1",
+  "version": "1.1.0-next.2",
+  "type": "module",
   "description": "Add support for WebSockets in Next.js 13 app directory",
-  "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",
@@ -19,19 +14,25 @@
   "bugs": {
     "url": "https://github.com/apteryxxyz/next-ws/issues"
   },
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "client",
-    "server"
-  ],
-  "main": "./index.js",
-  "types": "./index.d.ts",
+  "files": ["dist"],
+  "exports": {
+    "./client": {
+      "import": "./dist/client/index.mjs",
+      "require": "./dist/client/index.cjs",
+      "types": "./dist/client/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.cjs",
+      "types": "./dist/server/index.d.ts"
+    }
+  },
   "scripts": {
-    "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/"
+    "lint": "biome lint . --write",
+    "format": "biome format . --write",
+    "check": "tsc --noEmit",
+    "build": "cp ../../readme.md . && tsup",
+    "dev": "pnpm build --watch"
   },
   "peerDependencies": {
     "next": ">=13.1.1",
@@ -39,21 +40,11 @@
     "ws": "*"
   },
   "devDependencies": {
-    "@types/react": "^18",
-    "@types/react-dom": "^18",
-    "@types/ws": "^8",
-    "eslint": "^8.43.0",
-    "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"
-  },
-  "eslintConfig": {
-    "root": true,
-    "extends": [
-      "../../.eslintrc.js"
-    ]
+    "@configs/tsup": "workspace:^",
+    "@types/react": "^18.3.3",
+    "@types/ws": "^8.5.10",
+    "next": "^14.2.4",
+    "react": "^18.3.1",
+    "ws": "^8.17.1"
   }
 }

package/readme.md

@@ -0,0 +1,241 @@
+<div align="center">
+  <h1><strong>Next WS</strong></h1>
+  <i>Add support for WebSockets in Next.js app directory</i><br>
+  <code>npm install next-ws ws</code>
+</div>
+
+<div align="center">
+  <img alt="package version" src="https://img.shields.io/npm/v/next-ws?label=version">
+  <img alt="total downloads" src="https://img.shields.io/npm/dt/next-ws">
+  <br>
+  <a href="https://github.com/apteryxxyz/next-ws"><img alt="next-ws repo stars" src="https://img.shields.io/github/stars/apteryxxyz/next-ws?style=social"></a>
+  <a href="https://github.com/apteryxxyz"><img alt="apteryxxyz followers" src="https://img.shields.io/github/followers/apteryxxyz?style=social"></a>
+  <a href="https://discord.gg/vZQbMhwsKY"><img src="https://discordapp.com/api/guilds/829836158007115806/widget.png?style=shield" alt="discord shield"/></a>
+</div>
+
+
+
+## 🤔 About
+
+Next WS (`next-ws`) is an advanced Next.js plugin that seamlessly integrates WebSocket server capabilities directly into routes located in the **app directory**. With Next WS, you no longer require a separate server for WebSocket functionality.
+
+> [!IMPORTANT]  
+> Next WS is designed for use in server-based environments. It is not suitable for serverless platforms like Vercel, where WebSocket servers are not supported. Furthermore, this plugin is built for the app directory and does not support the older pages directory.
+
+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.
+
+
+## 🏓 Table of Contents
+
+## 📦 Installation
+
+Setting up a WebSocket server with Next WS involves patching your local Next.js installation. Next WS simplifies this process with a CLI command that automatically detects and patches your Next.js version, ensuring compatibility. Note that Next.js version 13.1.1 or higher is required.
+
+```sh
+npx next-ws-cli@latest patch
+```
+
+> [!NOTE]  
+> If at any point your local Next.js installation is changed or updated you will need to re-run the patch command.
+
+After successfully patching Next.js, install the Next WS package along with its peer dependency, ws, into your project:
+
+```sh
+npm install next-ws ws
+```
+
+## 🚀 Usage
+
+Using WebSocket functionality in your Next.js application with Next WS is simple and requires no additional configuration. Simply export a `SOCKET` function from any route file. This function will be invoked whenever a client establishes a WebSocket connection to that specific route.
+
+The `SOCKET` function receives three arguments: the WebSocket client instance, the incoming HTTP request - which you can use to get the URL path, query parameters, and headers - and the WebSocket server instance.
+
+```ts
+export function SOCKET(
+  client: import('ws').WebSocket,
+  request: import('http').IncomingMessage,
+  server: import('ws').WebSocketServer,
+) {
+  // ...
+}
+```
+
+### With a Custom Server
+
+In production, Next.js uses a worker process for routes, which can make it difficult to access the WebSocket server from outside a `SOCKET` handler, especially when the WebSocket server exists on the main process. For those needing to overcome this challenge or preferring a custom server setup, Next WS provides a solution.
+
+The `next-ws/server` module offers functions for setting the HTTP and WebSocket servers. You use these functions to tell Next WS to use your server instances instead of creating its own. This allows you to then access the instances you created yourself from anywhere in your app. Refer to the [example below](#-using-a-custom-server).
+
+## 🌀 Examples
+
+For more detailed examples, refer the [`examples` directory](https://github.com/apteryxxyz/next-ws/tree/main/examples).
+
+### Creating a Socket
+
+Creating an API route anywhere within the app directory and exporting a `SOCKET` function from it is all that is required. Below is an example of a simple echo server, which sends back any message it receives.
+
+```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,
+) {
+  console.log('A client connected');
+
+  client.on('message', (message) => {
+    console.log('Received message:', message);
+    client.send(message);
+  });
+
+  client.on('close', () => {
+    console.log('A client disconnected');
+  });
+}
+```
+
+### Using a Custom Server
+
+To use a custom server, all you need to do is tell Next WS to use your server instead of creating its own. This can be done by calling the `setHttpServer` and `setWebSocketServer` functions from `next-ws/server` and passing your server instances.
+
+```ts
+// server.js
+
+const { setHttpServer, setWebSocketServer } = require('next-ws/server');
+const { Server } = require('node:http');
+const { parse } = require('node:url');
+const next = require('next');
+const { WebSocketServer } = require('ws');
+
+const dev = process.env.NODE_ENV !== 'production';
+const hostname = 'localhost';
+const port = 3000;
+
+const httpServer = new Server();
+const webSocketServer = new WebSocketServer({ noServer: true });
+// Tell Next WS about the HTTP and WebSocket servers before starting the custom server
+setHttpServer(httpServer);
+setWebSocketServer(webSocketServer);
+
+const app = next({ dev, hostname, port, customServer: httpServer });
+const handle = app.getRequestHandler();
+
+app.prepare().then(() => {
+  httpServer
+    .on('request', async (req, res) => {
+      const parsedUrl = parse(req.url, true);
+      await handle(req, res, parsedUrl);
+    })
+    .listen(port, () => {
+      console.log(` ▲ Ready on http://${hostname}:${port}`);
+    });
+});
+```
+
+### Accessing the WebSocket Server
+
+Along with setters, Next WS also provides getters for the HTTP and WebSocket servers. These functions can be used to access the servers from anywhere in your app.
+
+> [!IMPORTANT]  
+> In order to use the `getWebSocketServer` and `getHttpServer` functions, you must be using a [custom server](https://nextjs.org/docs/advanced-features/custom-server), this is due to a limitation in Next.js. Refer to the [With a Custom Server](#-with-a-custom-server).
+
+```ts
+// app/api/stats/route.ts
+
+import { getWebSocketServer } from 'next-ws/server';
+// There is also a `getHttpServer` function available
+
+export function GET() {
+  const wsServer = getWebSocketServer();
+  // Response with the number of connected clients
+  return Response.json({ count: wsServer.clients.size });
+}
+```
+
+### Client-Side Utilities
+
+To make it easier to connect to your new WebSocket 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
+'use client';
+
+import { WebSocketProvider } from 'next-ws/client';
+
+export default function Layout({ children }: React.PropsWithChildren) {
+  return <html>
+    <body>
+      <WebSocketProvider
+        url="ws://localhost:3000/api/ws"
+      >
+        {children}
+      </WebSocketProvider>
+    </body>
+  </html>;
+}
+```
+
+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;
+}
+```
+
+Now you can use the `useWebSocket` hook to get the WebSocket instance, and send and receive messages.
+
+```tsx
+// page.tsx
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useWebSocket } from 'next-ws/client';
+
+export default function Page() {
+  const ws = useWebSocket();
+  //    ^? WebSocket on the client, null on the server
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [message, setMessage] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function onMessage(event: MessageEvent) {
+      const payload =
+        typeof event.data === 'string' ? event.data : await event.data.text();
+      const message = JSON.parse(payload) as Message;
+      setMessages((p) => [...p, message]);
+    }
+
+    ws?.addEventListener('message', onMessage);
+    return () => ws?.removeEventListener('message', onMessage);
+  }, [ws]);
+
+  return <>
+    <input
+      ref={inputRef}
+      type="text"
+    />
+
+    <button
+      onClick={() => ws?.send(inputRef.current?.value ?? '')}
+    >
+      Send message to server
+    </button>
+
+    <p>
+      {message === null
+        ? 'Waiting to receive message...'
+        : `Got message: ${message}`}
+    </p>
+  </>;
+}
+```

package/README.md

@@ -1,198 +0,0 @@
-<div align="center">
-  <h1><strong>Next WS</strong></h1>
-  <i>Add support for WebSockets in Next.js app directory</i><br>
-  <code>npm install next-ws ws</code>
-</div>
-
-<div align="center">
-  <img alt="package version" src="https://img.shields.io/npm/v/next-ws?label=version">
-  <img alt="total downloads" src="https://img.shields.io/npm/dt/next-ws">
-  <br>
-  <a href="https://github.com/apteryxxyz/next-ws"><img alt="next-ws repo stars" src="https://img.shields.io/github/stars/apteryxxyz/next-ws?style=social"></a>
-  <a href="https://github.com/apteryxxyz"><img alt="apteryxxyz followers" src="https://img.shields.io/github/followers/apteryxxyz?style=social"></a>
-  <a href="https://discord.gg/vZQbMhwsKY"><img src="https://discordapp.com/api/guilds/829836158007115806/widget.png?style=shield" alt="discord shield"/></a>
-</div>
-
----
-
-## 🤔 About
-
-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.
-
-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.
-
----
-
-## 🏓 Table of Contents
-
-- [🤔 About](#-about)
-- [🏓 Table of Contents](#-table-of-contents)
-- [📦 Installation](#-installation)
-- [🚀 Usage](#-usage)
-  - [🚓 Verify Patch](#-verify-patch)
-- [🌀 Example](#-example)
-  - [📁 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
-npx next-ws-cli@latest patch
-```
-
-> If at any point your local Next.js installation is changed or updated you will need to re-run the patch command.
-
-Once the patch is complete, you will need to install the Next WS package into your project.
-
-```sh
-npm install next-ws ws
-# ws is a peer dependency, you must install it as well
-```
-
-### 🚓 Verify Patch (Optional)
-
-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();
-```
-
----
-
-## 🚀 Usage
-
-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 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(
-  client: import('ws').WebSocket,
-  request: import('http').IncomingMessage,
-  server: import('ws').WebSocketServer,
-) {
-  // ...
-}
-```
-
-With this straightforward setup, you can fully leverage the capabilities of Next WS and efficiently handle WebSocket connections within your Next.js application.
-
----
-
-## 🌀 Example
-
-### 📁 Server
-
-Create an API route anywhere within the app directory, and export a `SOCKET` function from it, below is an example of a simple echo server, which sends back any message it receives.
-
-```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,
-) {
-  console.log('A client connected!');
-
-  client.on('message', message => {
-    client.send(message);
-  });
-  
-  client.on('close', () => {
-    console.log('A client disconnected!');
-  });
-}
-```
-
-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 completely optional, you can use your own implementation if you wish.
-
-```tsx
-// layout.tsx
-'use client';
-
-import { WebSocketProvider } from 'next-ws/client';
-
-export default function Layout() {
-  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;
-}
-```
-
-Now you can use the `useWebSocket` hook to get the WebSocket instance, and send and receive messages.
-
-```tsx
-// page.tsx
-'use client';
-
-import { useWebSocket } from 'next-ws/client';
-import { useCallback, useEffect, useState } from 'react';
-
-export default function Page() {
-  const ws = useWebSocket();
-  //    ^? WebSocket on the client, null on the server
-
-  const [value, setValue] = useState('');
-  const [message, setMessage] = useState<string | null>(null);
-
-  const onMessage = useCallback(
-    (event: MessageEvent<Blob>) =>
-      void event.data.text().then(setMessage),
-    [],
-  );
-  
-  useEffect(() => {
-    ws?.addEventListener('message', onMessage);
-    return () => ws?.removeEventListener('message', onMessage);
-  }, [onMessage, ws]);
-
-  return <>
-    <input
-      type="text"
-      value={value}
-      onChange={event => setValue(event.target.value)}
-    />
-
-    <button onClick={() => ws?.send(value)}>
-      Send message to server
-    </button>
-
-    <p>
-      {message === null
-        ? 'Waiting to receive message...'
-        : `Got message: ${message}`}
-    </p>
-  </>;
-}
-
-```

package/client/context.d.ts

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

@@ -1,43 +0,0 @@
-"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 instance = (0, react_1.useMemo)(() => {
-        if (!isBrowser)
-            return null;
-        const client = new WebSocket(url, protocols);
-        if (binaryType)
-            client.binaryType = binaryType;
-        return client;
-    }, [isBrowser, url, protocols]);
-    (0, react_1.useEffect)(() => {
-        if (instance?.readyState !== WebSocket.OPEN)
-            return;
-        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

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

package/client/index.js

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

package/index.d.ts

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

package/index.js

@@ -1,3 +0,0 @@
-"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/server/index.d.ts

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

package/server/index.js

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

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

@@ -1,42 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-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");
-function setupWebSocketServer(nextServer) {
-    const httpServer = (0, next_1.getHttpServer)(nextServer);
-    const wsServer = (0, ws_1.getWsServer)();
-    Log.ready('[next-ws] websocket server started successfully');
-    // 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;
-        if (pathname.startsWith('/_next'))
-            return;
-        const fsPathname = (0, next_1.resolvePathname)(nextServer, pathname);
-        if (!fsPathname) {
-            Log.error(`[next-ws] could not find module for page ${pathname}`);
-            return socket.destroy();
-        }
-        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();
-        }
-        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();
-        }
-        return wsServer.handleUpgrade(request, socket, head, (client, request) => void 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;