perf: build-time precompression + startup metadata cache for static serving

[NathanDrake2406]

This PR implements a static file serving method that is better than Next.js 16.2.

Bugs fixed

1. Event loop blocking — existsSync + statSync ran on every static file request, blocking SSR responses behind synchronous filesystem calls. Now zero FS calls per request (metadata cached at startup).
2. No 304 Not Modified — No ETag, no If-None-Match support. Every repeat visit re-downloaded every asset in full. Now returns 304 (200 bytes) when the browser already has the asset.
3. HEAD returned full body — HEAD requests streamed the entire file body. Now sends headers only, per HTTP spec.

Optimizations

1. Build-time precompression — .br (brotli q11), .gz (gzip l9), .zst (zstd l19) generated at build time. Zero compression CPU per request.
2. Startup metadata cache — Pre-computed response headers per variant. Zero object allocation in the hot path.
3. In-memory buffer serving — Small precompressed files (< 64KB) served via res.end(buffer) instead of createReadStream().pipe(), eliminating file descriptor overhead.
4. Zstandard support — First Node.js framework to serve .zst assets. 3-5x faster client-side decompression than brotli (Chrome 123+, Firefox 126+).
5. Async filesystem fallback — Non-cached files use fsp.stat() instead of blocking statSync.

Real-world impact

• SSR doesn't stall anymore. Before: 10 concurrent static file requests block the event loop with sync stat calls while SSR waits. Now: static serving is non-blocking with zero syscalls.
• Repeat visits transfer almost nothing. Before: full asset re-download on every revisit. Now: 304 response (200 bytes) instead of the full bundle.
• First visits transfer 70-80% less data. Before: raw uncompressed JS/CSS. Now: build-time brotli q11 or zstd. A 200KB bundle becomes ~50KB. On mobile, that's seconds saved.
• Server CPU drops to near zero for static assets. Before: brotli compression on every request. Now: pre-compressed at build time, served from memory.

Benchmark

_{Averaged over 10 runs. 5000 requests per run, 10 concurrent connections, 5 × 50KB JS bundles. vinext NEW won every single run.}

Throughput (Accept-Encoding: zstd, br, gzip)

	avg req/s	median req/s	min	max	vs vinext before
vinext (this PR)	24,716	25,997	12,564	29,276	2.9x faster
SvelteKit / sirv 3.0.2	15,088	15,838	7,309	18,284	1.8x faster
Next.js 16.2 / send 1.2.1	10,174	11,261	6,327	12,614	1.2x faster
vinext (before)	8,520	8,765	6,501	9,816	baseline

304 Not Modified (conditional request with matching ETag)

	req/s
vinext (this PR)	~30,000
SvelteKit / sirv 3.0.2	~17,000

Transfer size (5000 requests)

	Total transferred	Per-file compressed size	Compression
vinext (this PR)	508 KB	~101 B (zstd l19)	build-time, max quality
SvelteKit / sirv	454 KB	~93 B (brotli)	build-time
vinext (before)	459 KB	~94 B (brotli q4)	per-request, fast quality
Next.js / send	250,000 KB	51,200 B (none)	none

_{vinext serves zstd when accepted (trades ~12% larger output for 3-5x faster client-side decompression). When serving brotli, vinext produces the smallest output of all — brotli q11 (93 B) vs old vinext's q4 (94 B).}

Feature comparison

	vinext (this PR)	SvelteKit / sirv	Next.js / send	vinext (before)
Per-request FS calls	0	0	1 (stat)	2 (existsSync + statSync)
Event loop blocking	No	No	No	Yes (sync stat)
Precompression	zstd + brotli + gzip	brotli + gzip	none	none
Compression quality	max (build-time)	max (build-time)	N/A	fast (per-request)
Small file buffering	Yes (< 64KB in memory)	No (always streams)	No (always streams)	No
304 Not Modified	Yes	Yes	Yes	No
HEAD optimization	Yes	Yes	Yes	No
Zstandard	Yes	No	No	No
Content-Length	Yes (all responses)	Yes	Yes	No (compressed)
ETag	Yes	Yes	Yes	No

Why vinext beats sirv

sirv always uses createReadStream().pipe() — even for a 100-byte precompressed file, this opens a file descriptor, creates a ReadStream, sets up pipe plumbing, reads 100 bytes, and closes the fd. vinext buffers small files (< 64KB) in memory at startup and serves them with res.end(buffer) — a single write to the socket. For large files, it still streams. Best of both worlds.

Architecture

Build time:    precompressAssets()         → .br + .gz + .zst files on disk
Server boot:   StaticFileCache.create()    → scan dirs, cache metadata + buffers
Per request:   Map.get() → ETag check → res.writeHead(precomputed) → res.end(buf)

New modules:

• src/build/precompress.ts — build-time compression (brotli q11, gzip l9, zstd l19)
• src/server/static-file-cache.ts — startup cache with pre-computed headers + in-memory buffers
• prod-server.ts refactored tryServeStatic — async, cache-aware, precompressed variant serving

Test plan

• precompressAssets: generates .br/.gz/.zst, skips small files, skips non-compressible types, handles missing dirs, idempotent, correct decompression (13 tests)
• StaticFileCache: scan, lookup, HTML fallbacks, .vite/ blocking, etag, variant detection, nested dirs (20 tests)
• tryServeStatic: precompressed serving (zstd/br/gz fallback chain), 304 Not Modified, HEAD, Content-Length, Vary, extra headers, traversal protection (19 tests)
• Existing prod-server tests: 254 pass, zero regressions
• CI: format, lint, typecheck, vitest, playwright

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/vinext@641

commit: 75a0c8f