Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

HMR WebSocket fails - middlewareMode prevents Vite's WebSocket handler

Open
  • Is something wrong?
#175 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
55/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Tech stack
typescript, vite
Domain
tooling

Research direction

Start in src/adapter/dev-server.ts, focusing on the server configuration and startDev entry point described in the issue. Reproduce the failure with marko-run dev through a proxy and compare its WebSocket setup with raw Vite. Done means the proxied HMR connection receives 101 Switching Protocols instead of 404.

Written by the indexing model from the issue text.

Description

Summary

HMR WebSocket connections fail when using marko-run dev. The WebSocket upgrade request returns 404 instead of 101 Switching Protocols.

Environment

  • @marko/run: 0.9.3
  • vite: 7.2.2
  • Node.js: 20.x

Reproduce Steps

  1. Run marko-run dev
  2. Access the dev server through any proxy (Cloudflare Tunnel, nginx, etc.)
  3. Open browser DevTools → Network → WS filter
  4. Observe WebSocket returns 404, HMR doesn't work

Root Cause

In src/adapter/dev-server.ts:

server: { ...config?.server, middlewareMode: true }

Then in startDev:

const listener = devServer.middlewares.listen(port, ...);

The problem:

  • middlewareMode: true tells Vite NOT to create its own HTTP server (devServer.httpServer is null)
  • middlewares.listen() creates a NEW HTTP server
  • This new server doesn't have Vite's WebSocket upgrade handler attached
  • WebSocket upgrades get routed as HTTP GET → 404

Proof

  • Raw npx vite → WebSocket returns 101 Switching Protocols ✅
  • marko-run dev → WebSocket returns 404 ❌

Proposed Fix

// Don't use middlewareMode
server: { ...config?.server, middlewareMode: false }

// Use Vite's httpServer
devServer.httpServer.listen(port, ...);

Workaround

Users can use patch-package to patch node_modules/@marko/run/dist/adapter/index.js:

  1. Change middlewareMode: true to false
  2. Change devServer.middlewares.listen() to devServer.httpServer.listen()
Dominant language
TypeScript
Stars
175
Forks
16
Avg merge
3d 12h
Merged PRs (30d)
6

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from marko-js/run

All issues in marko-js/run

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.