🤔 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
• 🏓 Table of Contents
• 📦 Installation
• 🚀 Usage
  • 🚓 Verify Patch
• 🌀 Example
  • 📁 Server
  • 📁 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.

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.

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.

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.

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.

// 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.

// 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.

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.

// 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>
  </>;
}