Enable Next.js route handlers to handle WebSocket and other Upgrade requests

[AaronFriel]

Goals

1. Enable Next.js App Router to be used for low latency, bidirectional streams, e.g.: using Websockets.

Non-Goals

1. Enable custom servers or patches/shims that place websocket handling code outside of "App Router" norms.

Background

Websockets enable low latency, "sticky" communication channels with a backend. These are useful, for example, for rendering a terminal shell (xterm.js), for multiplayer experiences (socket.io), and for interactive chat.

Being able to host a websocket server directly in a route handler would enable these and many more applications.

Proposal

First, remove the .on('upgrade') handler in router-server:

next.js/packages/next/src/server/lib/router-server.ts

Lines 566 to 606 in 43b075e

	const upgradeHandler: WorkerUpgradeHandler = async (req, socket, head) => {
	try {
	req.on('error', (_err) => {
	// TODO: log socket errors?
	// console.error(_err);
	})
	socket.on('error', (_err) => {
	// TODO: log socket errors?
	// console.error(_err);
	})
	if (opts.dev && developmentBundler) {
	if (req.url?.includes(`/_next/webpack-hmr`)) {
	return developmentBundler.hotReloader.onHMR(req, socket, head)
	}
	}
	const { matchedOutput, parsedUrl } = await resolveRoutes({
	req,
	res: socket as any,
	isUpgradeReq: true,
	signal: signalFromNodeResponse(socket),
	})
	// TODO: allow upgrade requests to pages/app paths?
	// this was not previously supported
	if (matchedOutput) {
	return socket.end()
	}
	if (parsedUrl.protocol) {
	return await proxyRequest(req, socket as any, parsedUrl, head)
	}
	// If there's no matched output, we don't handle the request as user's
	// custom WS server may be listening on the same path.
	} catch (err) {
	console.error('Error handling upgrade request', err)
	socket.end()
	}
	}

This is in fact unnecessary for HMR. Adding an .on('upgrade') handler circumvents the HTTP server's ordinary routing and middleware. As I expect the most common use of middleware is security - whether handling session cookies, authentication or authorization - this is an anti-pattern.

Instead, add ws as a dependency (from a dev dependency), and modify the requestHandlerImpl like so:

  const requestHandlerImpl: WorkerRequestHandler = async (req, res) => {
    const isUpgradeReq = req?.method === 'GET' && req?.headers?.connection?.toLowerCase() === 'upgrade';

    if (isUpgradeReq && opts.dev && developmentBundler && req.url?.includes(`/_next/webpack-hmr`)) {
      return developmentBundler.hotReloader.onHMR(req, req.socket, Buffer.alloc(0));
    }

This preserves the same behavior for HMR / developer workflows, but it enables GET route handlers to receive upgrade requests.

Second, an upgrade response handler method to NextRequest. This is straightforward for the Node runtime to support, but may require some engineering for the Edge runtime (as seen in other edge runtimes).

With this handler providing access to the underlying request and socket, a WebSocket route is straightforward to implement.

import { NextRequest } from 'next/server'
import * as ws from 'ws'

export const dynamic = 'force-dynamic'

export const GET = async (req: NextRequest): Promise<Response> => {
  req.upgrade((request, socket) => {
    const server = new ws.WebSocketServer({ noServer: true })

    server.handleUpgrade(request, socket, Buffer.alloc(0), (ws) => {
      ws.on('message', (message) => {
        if (message.toString('utf8') === 'ping') {
          ws.send('pong')
        }
      })

      ws.on('error', (err) => {
        server.close()
      })

      ws.on('close', () => {
        server.close()
      })
    })
  })
}

Alternatively, an UPGRADE route handler could be added to support this use case.

[avarayr]

@AaronFriel I'm having the same issue because Next.JS doesn't allow me to handle Connection upgrade requests the way I want to.

2. Next.js listens for all "upgrade" events and closes the socket for any connection that matches an pages/api endpoint, https://github.com/vercel/next.js/blob/canary/packages/next/src/server/lib/router-server.ts#L598C16-L598C47
3. There are patches on github that get rid of that - https://github.com/apteryxxyz/next-ws/tree/main

Letting the API handler take over and handle the Upgrade requests will enable developers to customize how they want to deal with custom websocket solutions. Right now this is practically impossible without patching next.js.

---

If anyone stumbles upon this thread and is also building a TRPC integration with websockets and wants to have a websocket server on the same port as your website, here's my really long workaround.

Click here to see my really long workaround

This is how I worked around my niche but complicated issue - I needed next.js server to handle socket upgrade requests for the socket server to use the same port as next.js.

🛑 This will NOT work on vercel, use only if self-hosting using output: "standalone"

1. Use Next.JS instrumentation tools to startup a websocket server, which will be either (a) full-featured server during local development running on a separate port or (b) serverless websocketserver instance that will handle the connection upgrade requests
   Enable experimental instrumentation feature

const config = {
  experimental: {
    instrumentationHook: true,
  }
}

Create the instrumentation file

// src/instrumentation.ts (since Next.JS 14)
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    // Websockets are useless on Edge runtime
    const { BootstrapWS } = await import("./server/wssServer");

    BootstrapWS();
  }
}

// src/server/wssServer.ts

/* My use-case is TRPC Websocket adapter, you can customize your websocket handling as you wish */
import { applyWSSHandler } from "@trpc/server/adapters/ws";
import { WebSocketServer } from "ws";
import { appRouter } from "./api/root";
import { createWSContext } from "./api/trpc";

const globalForWS = globalThis as unknown as {
  wss: WebSocketServer | undefined;
};

export function BootstrapWS() {
  const host = "0.0.0.0";
  const port = Number(process.env.NEXT_PUBLIC_WS_PORT ?? 3001);
  let wss: WebSocketServer;

  if (process.env.NODE_ENV === "development") {
    wss = new WebSocketServer({
      host,
      port,
    });
    console.log(`✅ WebSocket Server listening on ws://${host}:${port}`);
  } else {
    wss = new WebSocketServer({
      noServer: true,
    });
    console.log(`✅🪄 Magic Serverless WebSocket Listening`);
  }

  /* My use-case is TRPC Websocket adapter, you can customize your websocket handling as you wish */
  const handler = applyWSSHandler({
    wss,
    router: appRouter,
    createContext: createWSContext,
  });

  globalForWS.wss = wss;

  process.on("SIGTERM", () => {
    console.log("SIGTERM");
    handler.broadcastReconnectNotification();
    wss.close();
  });
}

🤔 Just in case you need createWSContext

/**
 * Reads the JWT token from the next-auth session cookie, and returns the
 * session object by decoding the token. Returns null if the JWT token is absent
 * or invalid
 */
export async function getSessionFromCookie(
  opts: NodeHTTPCreateContextFnOptions<IncomingMessage, ws>,
): Promise<Session | null> {
  try {
    const cookies = opts.req.headers.cookie;

    const isSecure = process.env.NEXT_PUBLIC_BASE_URL?.startsWith("https://");
    const cookiePrefix = isSecure ? "__Secure-" : "";
    const fullCookieName = `${cookiePrefix}next-auth.session-token`;

    const sessionToken = cookies
      ?.split("; ")
      .find((c) => c.startsWith(fullCookieName))
      ?.split("=")?.[1];

    // decode will throw when the token is invalid
    const decoded = await jwt.decode({
      token: sessionToken,
      secret: String(process.env.NEXTAUTH_SECRET),
    });

    if (!decoded) return null;

    return {
      user: { id: String(decoded.sub) },
      expires: new Date(Number(decoded.exp) * 1000).toISOString(),
    };
  } catch (err: unknown) {
    return null;
  }
}

export const createWSContext = async (
  opts: NodeHTTPCreateContextFnOptions<IncomingMessage, ws>,
) => {
  const session = await getSessionFromCookie(opts);
  return {
    session,
  };
};

3. Create the pages/api/ws.ts to handle the websocket upgrades

# pages/api/ws.ts
import { type NextApiHandler } from "next";
import { type WebSocketServer } from "ws";

// globalThis
const globalForWS = globalThis as unknown as {
  wss: WebSocketServer | undefined;
};

const handler: NextApiHandler = (req, res) => {
  if (!globalForWS.wss) {
    res.status(500).send("wss not initialized");
    return;
  }
  // if not Connection: Upgrade, return 400
  if (req.headers.connection !== "Upgrade") {
    res.status(400).send("Expected Connection: Upgrade");
    return;
  }
  // if not Upgrade: websocket, return 400
  if (req.headers.upgrade !== "websocket") {
    res.status(400).send("Expected Upgrade: websocket");
    return;
  }

  const wsServer = globalForWS.wss;
  const request = req;

  if (!request) {
    res.status(500).send("Raw request not available");
    return;
  }

  if (!request.socket) {
    res.status(500).send("Socket not available");
    return;
  }

  wsServer.handleUpgrade(request, request.socket, Buffer.alloc(0), (ws) => {
    wsServer.emit("connection", ws, request);

    // eslint-disable-next-line @typescript-eslint/no-empty-function
    ws.on("error", () => {});
  });
};
export default handler;

5. On client side, you're gonna have to use a different port for websockets (e.g. 3001)

Modify the tRPC client-side src/utils/api.ts to use the correct websocket link depending on whether we're on local or prod.

# src/utils/api.ts
function getEndingLink(ctx: NextPageContext | undefined) {
  if (typeof window === "undefined") {
    return httpBatchLink({
      url: `${getBaseUrl()}/api/trpc`,
      headers() {
        if (!ctx?.req?.headers) {
          return {};
        }
        // To use SSR properly, you need to forward the client's headers to the server
        // This is so you can pass through things like cookies when we're server-side rendering
        // If you're using Node 18, omit the "connection" header
        const {
          // eslint-disable-next-line @typescript-eslint/no-unused-vars
          connection: _connection,
          ...headers
        } = ctx.req.headers;

        return {
          ...headers,
          // Optional: inform server that it's an SSR request
          "x-ssr": "1",
        };
      },
    });
  }

  /**
   * If we're on HTTPS, use WSS, else use WS
   */
  const protocol = window.location.protocol === "https:" ? "wss" : "ws";
  const url =
    process.env.NODE_ENV === "development"
      ? `${protocol}://localhost:${process.env.NEXT_PUBLIC_WS_PORT}`
      : `${protocol}://${window.location.host}/api/ws`;

  return wsLink<AppRouter>({
    client: createWSClient({
      url,
    }),
  });
}




// .....
// Modify the links as follows
links: [
        ...
        getEndingLink(ctx), // at the end of links
],

And finally, create a patch script to execute after next build

// /patch-standalone.js

/* eslint-disable @typescript-eslint/no-var-requires */
/*
We need to patch the next.js standalone server to disable the socket upgrade event
*/
const { existsSync, readFileSync, writeFileSync } = require('fs');
const path = require('path');


const NEEDLE = `server.on("upgrade",`;
const PATCH = `server.on("__upgrade_disabled",`;
const PATH = path.join(__dirname, '.next/standalone/node_modules/next/dist/server/lib/start-server.js');

// if path exists
if (!existsSync(PATH)) {
  console.log('Cannot find path ' + PATH)
  process.exit(1)
}

const content = readFileSync(PATH, 'utf8');
if (content.includes(PATCH)) {
  console.log('Already patched')
  process.exit(0)
}

if (!content.includes(NEEDLE)) {
  console.log('Unexpected content, cannot patch');

  process.exit(1)
}

const patched = content.replace(NEEDLE, PATCH);

console.log('Patched ' + PATH);
writeFileSync(PATH, patched);
process.exit(0);

Then modify your build script in package.json

"scripts": {
    "build": "next build && node patch-standalone.js",
 // ...
}

[AaronFriel]

@avarayr I created a PR with the changes I propose, although it likely doesn't have the final developer UX Vercel will want.

It allows upgrading to any binary protocol too, it could be used for SSH over HTTPS or anything else.

[avarayr]

I've looked over the PR and it looks fantastic. Although I do agree that the DX could be improved.
Having the possibility of a Websocket server integration with next.js would be a game changer in many real-time applications.

[AaronFriel]

@avarayr I've updated the PR and the API is more to my liking now, the NextRequest#upgrade method is a handler that behaves in a manner similar to redirect and company in next/navigation. The route handler is quite a bit simpler.

[taylor-lindores-reeves]

Has there been any progress on this on Vercel's front? Do we have a simple way of upgrading NextJS to support websocket connections in 2024?

[MasterProvider]

any update on this to make Websocket stable feature on NEXTJS

[sim391calado]

I'm looking for a solution to socket.io on app router too

[taylor-lindores-reeves]

This should 100% be a feature on NextJS!