feat: replace separate WebSocket server with Next.js custom server

[Copilot]

Homarr

Thank you for your contribution. Please ensure that your pull request meets the following pull request:

• Builds without warnings or errors (pnpm build, autofix with pnpm format:fix)
• Pull request targets dev branch
• Commits follow the conventional commits guideline
• No shorthand variable names are used (eg. x, y, i or any abbrevation)
• Documentation is up to date. Create a pull request here.

---

POC to eliminate the standalone apps/websocket Node.js process by integrating the WebSocket server directly into a Next.js custom server, as described in the Socket.io guide.

Approach

apps/nextjs/server.ts creates a single http.createServer that:

1. Delegates HTTP to next().getRequestHandler()
2. Intercepts upgrade on /websockets → ws.WebSocketServer({ noServer: true })
3. Applies applyWSSHandler with identical tRPC context/auth as the old standalone server

server.on("upgrade", (req, socket, head) => {
  if (req.url?.startsWith("/websockets")) {
    wss.handleUpgrade(req, socket, head, (ws) => {
      wss.emit("connection", ws, req);
    });
  }
});

Changes

• apps/nextjs/server.ts — Custom server: Next.js + integrated WS via @trpc/server/adapters/ws
• apps/nextjs/package.json — dev uses tsx server.ts, start uses node customServer.cjs, build step added for esbuild bundling
• apps/nextjs/…/trpc.tsx — WebSocket URL changed from port 3001 → 3000 (same process now)
• apps/websocket/package.json — dev script is now a no-op
• Root package.json — start no longer spawns wssServer.cjs
• scripts/run.sh — Single node apps/nextjs/customServer.cjs replaces wssServer.cjs + server.js
• nginx.conf — /websockets proxy target changed to port 3000
• Dockerfile — Copies customServer.cjs instead of wssServer.cjs
• scripts/benchmark-memory.sh — Memory measurement script for both approaches

Benchmark (dev mode, idle after startup)

	Separate (current)	Integrated (this PR)
WS server process	~208 MB	—
Next.js main	~1,473 MB	~1,771 MB
Next.js workers	~945 MB	0 MB
Total RSS	~2,626 MB	~1,771 MB
Δ		−855 MB (−32.6%)

One fewer Node.js V8 heap plus reduced worker spawning overhead.

Notable detail

next/dist/server/node-environment-baseline must be imported before anything else — it sets globalThis.AsyncLocalStorage which Next.js internals require at module load time.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• fonts.googleapis.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/homarr/homarr/node_modules/.bin/next build l/openssl/include k/v1�� bcrypt --external:@opentelemetry/api --external:deasync --external:cpu-features --loader:.html=text --loader:.scss=text --loader:.node=text credential.username -features/build/node_gyp_bins/as (dns block)
• homarr.dev
  • Triggering command: /opt/hostedtoolcache/node/24.13.1/x64/bin/node /opt/hostedtoolcache/node/24.13.1/x64/bin/node --require /home/REDACTED/work/homarr/homarr/node_modules/tsx/dist/preflight.cjs --import file:///home/REDACTED/work/homarr/homarr/node_modules/tsx/dist/loader.mjs ./src/docs/codegen.ts --global node_modules/.bin/sh user.name l/config (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Idea is to use a NextJS custom server : https://socket.io/fr/how-to/use-with-nextjs

https://nextjs.org/docs/pages/guides/custom-server

To replace the ws server (the whole app)

Make it so that the ws server is not ran on dev anymore and instead implement a custom NextJS server to replace that ws server app.

This has to be just a POC and not necessarily cover all of the features of the current ws server.

In order to validate that these changes are valid, you must benchmark the memory usage of both approaches (current ws separated nodejs app vs NextJS custom server)

Report the benchmarks on the PR and explain the changes in a succinct way. Ignore lint and formatting issues.

Start by executing and logging the memory usage of the current approach and at the end run the same script to compare. Just a simple benchmark sh test.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[deepsource-io]

DeepSource Code Review

We reviewed changes in 1161bbd...835ecd0 on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade   Focus Area: Reliability

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
JavaScript		Feb 28, 2026 9:15a.m.	Review ↗