next-ws 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+<center>
+    <h1><strong>Next WS</strong></h1>
+    <i>Add support for WebSockets in Next.js 13 app directory</i><br>
+    <code>npm install next-ws</code>
+</center>
+
+<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 Banner 2"/></a>
+</center>
+
+## 🤔 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.
+
+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](#-api)
+- [🌀 Example](#-example)
+  - [📁 Server](#-server)
+  - [📁 Client](#-client)
+
+---
+
+## 📦 Installation
+
+```sh
+npm install next-ws
+yarn add next-ws
+pnpm add next-ws
+```
+
+Upon installation, Next WS will automatically patch your existing Next.js installation to add support for WebSockets in API routes in the app directory. 
+
+<details>
+    <summary><strong>Caveats</strong></summary>
+
+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>
+
+---
+
+## 🚀 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.
+
+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.
+
+```ts
+export function SOCKET(
+    client: import('ws').WebSocket,
+    request: import('http').IncomingMessage,
+) {
+    // ...
+}
+```
+
+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,
+) {
+    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 not required, you can use the native WebSocket API if you prefer.
+
+```tsx
+// layout.tsx
+'use client';
+
+import { WebSocketProvider } from 'next-ws/client';
+
+export default function Layout() {
+    return <WebSocketProvider url="ws://localhost:3000/api/ws">
+        {...}
+    </WebSocketProvider>;
+}
+```
+
+```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>('');
+
+    const onMessage = useCallback((event: MessageEvent) => {
+        const text = await event.data.text();
+        setMessage(text);
+    }, []);
+
+    useEffect(() => {
+        ws?.addEventListener('message', onMessage);
+        return () => ws?.removeEventListener('message', onMessage);
+    }, []);
+
+    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 for server to send a message...'
+                : `Got message: ${message}`}
+        </p>
+    </>
+}
+```

package/package.json

@@ -0,0 +1,67 @@
+{
+    "name": "next-ws",
+    "private": false,
+    "version": "0.1.0",
+    "description": "Add support for WebSockets in Next.js 13 app directory",
+    "packageManager": "yarn@3.6.0",
+    "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"
+    },
+    "bugs": {
+        "url": "https://github.com/apteryxxyz/next-ws/issues"
+    },
+    "files": ["{client,server,patch}.{js,d.ts}"],
+    "scripts": {
+        "build": "tsc",
+        "clean": "rimraf ./*.{js,d.ts,js.map}",
+        "lint": "eslint --ext .ts,.tsx src",
+        "format": "prettier --write src/**/*.{ts,tsx} && eslint --fix --ext .ts,.tsx src/",
+        "postinstall": "node patch.js"
+    },
+    "dependencies": {
+        "@babel/generator": "^7.22.3",
+        "@babel/parser": "^7.22.4",
+        "@babel/template": "^7.21.9"
+    },
+    "peerDependencies": {
+        "next": "*",
+        "react": "*",
+        "ws": "*"
+    },
+    "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/ws": "^8",
+        "@typescript-eslint/eslint-plugin": "^5.59.8",
+        "@typescript-eslint/parser": "^5.59.8",
+        "eslint": "^8.41.0",
+        "eslint-config-apteryx": "^2.1.6",
+        "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",
+        "prettier": "^2.8.8",
+        "prettier-config-apteryx": "^2.1.0",
+        "react": "^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"
+}