next-ws

To enable WebSocket support, you must patch your local Next.js installation. Add a prepare script to your package.json. This ensures that next-ws patch runs automatically during installation, keeping your Next.js installation patched.

Important Note: next-ws is designed for server-based environments. It is not suitable for serverless platforms like Vercel, as they do not support WebSocket servers. This plugin is built specifically for the Next.js app directory and does not support the pages directory.

{
  "scripts": {
    "prepare": "next-ws patch"
  }
}

To use WebSockets in your Next.js app directory, install next-ws along with its peer dependency ws using your preferred package manager.

npm install next-ws ws
# or
pnpm add next-ws ws
# or
yarn add next-ws ws

To handle WebSocket connections, export a handler from your Next.js page module. The library looks for specific exported names in the userland of the imported module.

Recommended: UPGRADE handler

This is the preferred method. It provides access to the full Next.js request object and runs within an AsyncLocalStorage context.

Signature: async (client: WebSocket, wsServer: WebSocketServer, request: NextRequest, context: { params: any }) => void

Deprecated: SOCKET handler

Signature: async (client: WebSocket, message: any, wsServer: WebSocketServer, context: { params: any }) => (closeHandler?: () => void) | Promise<(closeHandler?: () => void) | void>

To create an echo server, export the UPGRADE function from an API route (e.g., app/api/ws/route.ts). Inside the function, listen for the message event on the client and send the received message back to the client.

// app/api/ws/route.ts (can be any route file in the app directory)

export function UPGRADE(
  client: import('ws').WebSocket,
  server: import('ws').WebSocketServer
) {
  console.log('A client connected');

  client.on('message', (message) => {
    console.log('Received message:', message);
    client.send(message);
  });

  client.once('close', () => {
    console.log('A client disconnected');
  });
}

In the Next.js app directory, you can handle WebSocket connections by exporting an UPGRADE function from an API route file. This function is called when a client attempts to upgrade an HTTP connection to a WebSocket connection.

The UPGRADE function receives the following arguments:

• client: The import('ws').WebSocket instance representing the connected client.
• server: The import('ws').WebSocketServer instance.
• request: The import('next/server').NextRequest object.
• context: The import('next-ws/server').RouteContext containing route-specific information.

export function UPGRADE(
  client: import('ws').WebSocket,
  server: import('ws').WebSocketServer,
  request: import('next/server').NextRequest,
  context: import('next-ws/server').RouteContext<'/api/ws'>,
) {
  // ...
}

The SetupOptions object allows you to provide an adapter to enable cross-server communication (e.g., via Redis). When an adapter is configured:

• The server subscribes to adapter messages for the specific pathname to broadcast to local clients.
• Incoming client messages are automatically broadcasted via adapter.broadcast(pathname, data).
• The adapter is automatically cleaned up when the HTTP server closes.

export interface SetupOptions {
  adapter?: Adapter;
}

The next-ws package provides utility functions to retrieve or modify the global server instances (HTTP and WebSocket) and the active adapter. These are useful for accessing the underlying server objects after initialization or for manual reconfiguration.

import {
  getHttpServer,
  getWebSocketServer,
  getAdapter,
  setHttpServer,
  setWebSocketServer,
  setAdapter
} from 'next-ws';

const httpServer = getHttpServer();
const wss = getWebSocketServer();
const adapter = getAdapter();

The useWebSocket hook allows you to access the current WebSocket instance from any component wrapped within a WebSocketProvider.

Note: This hook is deprecated. Use your own implementation instead.

Error Handling: If useWebSocket is called outside of a WebSocketProvider, it will throw the following error: useWebSocket must be used within a WebSocketProvider

import { useWebSocket } from './path-to-context';

function MyComponent() {
  const socket = useWebSocket();

  useEffect(() => {
    if (socket) {
      socket.onmessage = (event) => console.log(event.data);
    }
  }, [socket]);

  return <div>WebSocket Status: {socket ? 'Connected' : 'Disconnected'}</div>;
}

The next-ws client-side entrypoint exports the React context provider and hooks used to manage WebSocket connections within a React application. You should wrap your application (or the relevant part of your component tree) with the provider exported from this module to enable WebSocket functionality in child components.

import { NextWsProvider } from './client';

function App() {
  return (
    <NextWsProvider url="ws://localhost:8080">
      <YourComponent />
    </NextWsProvider>
  );
}