vite preview over HTTP/2: @polka/compression middleware appears to break text/event-stream (SSE) — concurrent fetches stall

[rsergeenko]

Description

Posting this as a discussion since I think it's a bug but the previous report on the same code path (#15987) was a discussion too, and I'd like to confirm before filing.

What we see

Under vite preview with HTTPS (so HTTP/2 is in play), opening a long-lived text/event-stream response via fetch and then making concurrent fetch calls on the same connection causes the concurrent calls to hang pending in DevTools for 10–30s. Page navigations away from a route that holds an open SSE stream visibly stall — the destination route's __data.json (or any other concurrent fetch) is the one that gets stuck.

The mechanism: vite preview unconditionally registers @polka/compression ahead of every response (packages/vite/src/node/preview.ts:239). When the request has Accept-Encoding: gzip, polka wraps res.writeHead/write/end/on and defers writeHead to its start() function — even when the response is text/event-stream and won't actually be compressed (chunked SSE has no Content-Length, fails polka's size >= threshold check). The wrapping itself, not the compression, is what corrupts the HTTP/2 stream lifecycle when the SSE stream is aborted client-side.

Isolation

Stripping Accept-Encoding for the SSE URL via a configurePreviewServer plugin (which makes polka take its if (!encoding) return next(); early-return and skip wrapping res) fully resolves the symptom. That isolates the bug to polka's response-wrapping under HTTP/2, not to compression of SSE itself.

Where we hit it

SvelteKit 2.63.1 switched query.live to SSE (sveltejs/kit#15957). Every navigation away from a route with an open live query stalls under vite preview — our e2e tests time out, manual preview sessions feel broken. Production deploys (adapter-node) are unaffected. Not specific to SvelteKit; reproduces with any SSE consumer using fetch over HTTP/2 preview.

Related

• #15987 — same code path, different symptom (ERR_HTTP2_INVALID_STREAM), still open
• lukeed/polka#221 — community-contributed Polka patch, unmerged since 2025-05

Question

Is this a known limitation, or should we file a bug? If a fix is desired, the obvious shapes would be:

• bump bundled @polka/compression once lukeed/polka#221 or equivalent lands
• guard app.use(compression()) in packages/vite/src/node/preview.ts to skip SSE paths
• expose a preview.compression option so consumers can opt out

Happy to put up a PR if a direction is preferred.

System info

Vite 8.0.16 / Node 22 / Chromium 148. Reproduced on Vite 7.x as well.

[hellyoshaqiqie17]

Hi! This is definitely a bug and you should file it (or put up a PR!).

The issue of @polka/compression breaking stream lifecycles under HTTP/2 preview server is indeed related to the way it intercepts and wraps the response lifecycle without checking if the response is a Server-Sent Event stream (text/event-stream). Since SSE uses long-lived connections, wrapping it with polka compression breaks concurrent streams and causes navigations to hang.

To fix this temporarily in Vite custom configuration, you can use a plugin with configurePreviewServer to strip Accept-Encoding for SSE endpoints so polka's compression middleware bypasses them:

// vite.config.js
export default {
  plugins: [{
    name: 'bypass-sse-compression',
    configurePreviewServer(server) {
      server.middlewares.use((req, res, next) => {
        if (req.headers['accept'] === 'text/event-stream' || req.url.includes('/sse-endpoint')) {
          delete req.headers['accept-encoding'];
        }
        next();
      });
    }
  }]
}

Putting up a PR in Vite's packages/vite/src/node/preview.ts to check the response content type or skip compression for text/event-stream would be the best permanent fix. For example, in preview.ts:

// Skip compression for SSE
if (req.headers['accept'] === 'text/event-stream') {
  return next();
}

[MILLERMARRU]

This does look like a genuine bug in the way vite preview wires up @polka/compression, and it reproduces directly against current source.

At packages/vite/src/node/preview.ts:234, the compression middleware gets attached unconditionally with no options: app.use(compression()). Looking at @polka/compression's implementation, the decision to compress is based on a regex test against the Content-Type header: mimes = /text|javascript|\/json|xml/i. Since text/event-stream contains the substring text, it matches and gets treated as compressible, even though SSE responses are meant to be pushed as soon as each event is written.

This isn't unique to @polka/compression either. Express's popular compression middleware, backed by the compressible package, would make the same call here, since text/event-stream matches its fallback ^text\/ regex too. It's a widely known gotcha with generic compression middleware sitting in front of SSE, which is why most implementations expose a way to skip specific routes or content types, something Vite's preview server currently has no escape hatch for.

Once compression kicks in, res.write gets routed through a zlib.createGzip() transform. Node's gzip buffers internally and only emits data once its buffer fills or .flush() is called, and @polka/compression never calls .flush() after a write. So SSE events sit inside the gzip transform instead of reaching the socket right away, matching the stalls described here and why concurrent requests on the same HTTP/2 connection show as pending in DevTools.

A workaround that avoids touching Vite itself: configurePreviewServer runs before Vite installs its own middlewares, so stripping accept-encoding on requests to the SSE route short circuits @polka/compression entirely, since it reads req.headers['accept-encoding'] up front and calls next() immediately when nothing matches.

function noCompressSse() {
  return {
    name: 'no-compress-sse',
    configurePreviewServer(server) {
      server.middlewares.use((req, res, next) => {
        if (req.url?.startsWith('/api/stream')) {
          delete req.headers['accept-encoding']
        }
        next()
      })
    },
  }
}

The real fix belongs upstream: @polka/compression's mimes regex would need an explicit exclusion for event-stream, or Vite's preview server would need to skip compression whenever the outgoing Content-Type is text/event-stream. Filing this against vitejs/vite with the exact line reference is probably the fastest path, since #15987 mentioned here seems to have gone stale without a resolution.

[LizunovSergey]

Your diagnosis holds up, and it's worth separating it from the one above, because the two point at different mechanisms and only one of them survives contact with the source.

I read @polka/compression@1.0.0-next.25 — the exact version packages/vite/package.json pins — and ran the middleware standalone, wired the way preview.ts:255 wires it (app.use(compression()), no options).

Compression does not engage for ordinary SSE. start() gates on compressible && cleartext && size >= threshold (build.mjs:53). size comes from Content-Length or, absent that, from the bytes accumulated so far (build.mjs:46) — and start() is invoked from res.write after only the first chunk has been counted (build.mjs:91-92). Chunked SSE has no Content-Length, so the gate is effectively "is the first event alone ≥ 1024 bytes". For normal-sized events it isn't, compress is never created, and writes fall through uncompressed at build.mjs:93.

So the gzip-buffering explanation doesn't apply to the typical case. text/event-stream does match MIMES (build.mjs:6) as noted above — that part is right — but matching the regex isn't sufficient to reach createGzip.

What actually breaks is the wrapping, exactly as you said. Two things, both independent of whether compression runs:

1. res.writeHead is replaced with a function that records pendingStatus and returns without calling through (build.mjs:83-88). The real writeHead fires only from inside start() (build.mjs:78), i.e. on the first write. An SSE handler that calls writeHead to flush headers and then streams gets no headers on the wire until its first event.

2. res.on queues listeners into pendingListeners instead of attaching them (build.mjs:106-111); they're attached in start() (build.mjs:75). If the response never gets a write, start() never runs and those listeners are never attached at all.

Measured, HTTP/1.1, handler calls writeHead immediately and writes its first event at 400 ms:

small SSE events : {"tHeaders":422,"contentEncoding":"(none)"}
first chunk 2KB  : {"tHeaders":4,"contentEncoding":"gzip"}

Headers are held for the full 400 ms and nothing is compressed. The 2 KB row is the corner where the threshold is cleared — there text/event-stream really does get gzipped, with no flush() anywhere in the file, so that concern is real but only for streams whose opening chunk is large.

Second probe — client aborts before the server writes anything, res.on('close') registered in the handler:

without compression : ["close"]
with compression    : []

That's the one I'd point at for your symptom. The cleanup handler an SSE route registers on res never fires when the client goes away before the first event, so per-stream teardown is skipped. On HTTP/2, where those streams share a connection, that is a much better fit for "concurrent fetches hang pending for 10-30 s" than compression latency would be, and it explains why it shows up on abort specifically rather than during steady streaming.

Both probes are ~40 lines of node:http plus the middleware, no Vite involved, so this is upstream behaviour rather than anything preview-specific.

On the three directions you listed: stripping accept-encoding works because it hits the !encoding early return at build.mjs:33 and skips the wrapping entirely — which is consistent with everything above, and is why it fixes the symptom even though nothing was being compressed.

For an upstream fix, gating on the request's Accept header is unreliable — EventSource sends text/event-stream, but a plain fetch() reading a stream often doesn't, which is the case you're hitting. The response Content-Type is the honest signal, and it isn't known until the handler sets it. Given that, passing a mimes regex that excludes event-stream into the existing option (build.mjs:21) is the smallest change that fits the current API — though note it only prevents the gzip case, not the writeHead/on deferral, which happens for every compressible-encoding request regardless. Fixing the stall itself means either the polka patch you linked or not wrapping responses whose headers are already flushed.

Worth filing, and worth splitting: the deferral is a @polka/compression bug, while "preview has no way to opt out" is the Vite-side gap.