Docs: webpack HMR conflicts with other websocket servers on the same port

What is the improvement or update you wish to see?

The docs should tell you not to run a websocket server on the same port as your NextJS server, because it will break webpack HMR.

Is there any context that might help us understand?

Several months ago I upgraded from NextJS 11 to 14. I also upgraded several GraphQL dependencies in an adjacent commit.

After upgrading, webpack HMR was broken, in roughly the same manner described in #32174.

Just today, I realized that if I used the WebSocketServer configuration for noServer, and handled the websocket upgrade manually, this resolved the problem. Essentially I had to make this change:

   const wsServer = new WebSocketServer({
-    server: httpServer,
+    noServer: true,
     path: GRAPHQL_SUBSCRIPTIONS_PATH,
   })
+  httpServer.on("upgrade", (request, socket, head) => {
+    if (request.url.startsWith(GRAPHQL_SUBSCRIPTIONS_PATH)) {
+      wsServer.handleUpgrade(request, socket, head, (ws) => {
+        wsServer.emit("connection", ws, request)
+      })
+    }
+  })

The upgrade handler may additionally want to check the sec-websocket-protocol header, depending on the use case.

I'm happy to make this change to docs myself, but I'm not sure where to put it. Can you advise? Thank you.

Does the docs page already exist? Please link to it.

No response

No documentation page is linked. Start by searching the docs for webpack HMR, custom servers, and WebSocketServer guidance; identify the most relevant page. Add a warning about sharing the Next.js server port with another websocket server and explain that manual upgrade handling may be needed, then verify the rendered documentation.