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

packages/vinext/src/build/precompress.ts

@@ -0,0 +1,147 @@
+/**
+ * Build-time precompression for hashed static assets.
+ *
+ * Generates .br (brotli q5), .gz (gzip l9), and .zst (zstd l22) files
+ * alongside compressible assets in dist/client/assets/. Served directly by
+ * the production server — no per-request compression needed for immutable
+ * build output.
+ *
+ * Only targets assets/ (hashed, immutable) — public directory files use
+ * on-the-fly compression since they may change between deploys.
+ */
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+import { promisify } from "node:util";
+
+const brotliCompress = promisify(zlib.brotliCompress);
+const gzip = promisify(zlib.gzip);
+const zstdCompress = typeof zlib.zstdCompress === "function" ? promisify(zlib.zstdCompress) : null;
+
+/** File extensions worth compressing (text-based, not already compressed). */
+const COMPRESSIBLE_EXTENSIONS = new Set([
+  ".js",
+  ".mjs",
+  ".css",
+  ".html",
+  ".json",
+  ".xml",
+  ".svg",
+  ".txt",
+  ".map",
+  ".wasm",
+]);
+
+/** Below this size, compression overhead exceeds savings. */
+const MIN_SIZE = 1024;
+
+/** Max files to compress concurrently (avoids memory spikes). */
+const CONCURRENCY = Math.min(os.availableParallelism(), 16);
+
+export interface PrecompressResult {
+  filesCompressed: number;
+  totalOriginalBytes: number;
+  /** Sum of brotli-compressed sizes (used for compression ratio reporting). */
+  totalCompressedBytes: number;
+}
+
+/**
+ * Walk a directory recursively, yielding relative paths for regular files.
+ */
+async function* walkFiles(dir: string, base: string = dir): AsyncGenerator<string> {
+  let entries;
+  try {
+    entries = await fsp.readdir(dir, { withFileTypes: true });
+  } catch {
+    return; // directory doesn't exist
+  }
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFiles(fullPath, base);
+    } else if (entry.isFile()) {
+      yield path.relative(base, fullPath);
+    }
+  }
+}
+
+/**
+ * Precompress all compressible hashed assets under `clientDir/assets/`.
+ *
+ * Writes `.br`, `.gz`, and `.zst` files alongside each original.
+ * Safe to re-run — overwrites existing compressed variants with identical
+ * output, and never compresses `.br`, `.gz`, or `.zst` files themselves.
+ */
+export async function precompressAssets(clientDir: string): Promise<PrecompressResult> {
+  const assetsDir = path.join(clientDir, "assets");
+  const result: PrecompressResult = {
+    filesCompressed: 0,
+    totalOriginalBytes: 0,
+    totalCompressedBytes: 0,
+  };
+
+  // Collect compressible files first, then process in bounded chunks
+  const files: { fullPath: string; content: Buffer }[] = [];
+
+  for await (const relativePath of walkFiles(assetsDir)) {
+    const ext = path.extname(relativePath).toLowerCase();
+
+    // Skip non-compressible types and already-compressed variants
+    if (!COMPRESSIBLE_EXTENSIONS.has(ext)) continue;
+    if (
+      relativePath.endsWith(".br") ||
+      relativePath.endsWith(".gz") ||
+      relativePath.endsWith(".zst")
+    )
+      continue;
+
+    const fullPath = path.join(assetsDir, relativePath);
+    const content = await fsp.readFile(fullPath);
+
+    if (content.length < MIN_SIZE) continue;
+
+    files.push({ fullPath, content });
+    result.filesCompressed++;
+    result.totalOriginalBytes += content.length;
+  }
+
+  // Process in chunks to bound concurrent CPU-heavy compressions
+  for (let i = 0; i < files.length; i += CONCURRENCY) {
+    const chunk = files.slice(i, i + CONCURRENCY);
+    await Promise.all(
+      chunk.map(async ({ fullPath, content }) => {
+        // Compress all variants concurrently within each file
+        const compressions: Promise<Buffer>[] = [
+          brotliCompress(content, {
+            params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 5 },
+          }),
+          gzip(content, { level: zlib.constants.Z_BEST_COMPRESSION }),
+        ];
+        if (zstdCompress) {
+          compressions.push(
+            zstdCompress(content, {
+              params: { [zlib.constants.ZSTD_c_compressionLevel]: 22 },
+            }),
+          );
+        }
+
+        const results = await Promise.all(compressions);
+        const [brContent, gzContent, zstdContent] = results;
+
+        const writes = [
+          fsp.writeFile(fullPath + ".br", brContent),
+          fsp.writeFile(fullPath + ".gz", gzContent),
+        ];
+        if (zstdContent) {
+          writes.push(fsp.writeFile(fullPath + ".zst", zstdContent));
+        }
+        await Promise.all(writes);
+
+        result.totalCompressedBytes += brContent.length;
+      }),
+    );
+  }
+
+  return result;
+}

packages/vinext/src/cli.ts

@@ -98,6 +98,7 @@ interface ParsedArgs {
   turbopack?: boolean; // accepted for compat, always ignored
   experimental?: boolean; // accepted for compat, always ignored
   prerenderAll?: boolean;
+  noPrecompress?: boolean;
 }
 
 function parseArgs(args: string[]): ParsedArgs {
@@ -114,6 +115,9 @@ function parseArgs(args: string[]): ParsedArgs {
       result.experimental = true; // no-op
     } else if (arg === "--prerender-all") {
       result.prerenderAll = true;
+    } else if (arg === "--no-precompress") {
+      result.noPrecompress = true;
+      process.env.VINEXT_NO_PRECOMPRESS = "1";
     } else if (arg === "--port" || arg === "-p") {
       result.port = parseInt(args[++i], 10);
     } else if (arg.startsWith("--port=")) {
@@ -509,6 +513,13 @@ async function buildApp() {
     prerenderResult = await runPrerender({ root: process.cwd() });
   }
 
+  // Precompression now runs as a Vite plugin writeBundle hook (vinext:precompress).
+  // The plugin auto-detects the deployment target: skips for Cloudflare Workers
+  // and Nitro (edge platforms handle compression at the CDN layer), runs for
+  // Node.js production server targets.
+  //
+  // --no-precompress is forwarded via VINEXT_NO_PRECOMPRESS env var.
+
   process.stdout.write("\x1b[0m");
   await printBuildReport({
     root: process.cwd(),
@@ -677,6 +688,8 @@ function printHelp(cmd?: string) {
     --verbose            Show full Vite/Rollup build output (suppressed by default)
     --prerender-all      Pre-render discovered routes after building (future releases
                          will serve these files in vinext start)
+    --no-precompress     Skip build-time precompression of static assets (useful when
+                         deploying behind a CDN that handles compression)
     -h, --help           Show this help
 `);
     return;

packages/vinext/src/index.ts

@@ -35,6 +35,7 @@ import { logRequest, now } from "./server/request-log.js";
 import { normalizePath } from "./server/normalize-path.js";
 import { findInstrumentationFile, runInstrumentation } from "./server/instrumentation.js";
 import { PHASE_PRODUCTION_BUILD, PHASE_DEVELOPMENT_SERVER } from "./shims/constants.js";
+import { precompressAssets } from "./build/precompress.js";
 import { validateDevRequest } from "./server/dev-origin-check.js";
 import {
   isExternalUrl,
@@ -1166,6 +1167,19 @@ export interface VinextOptions {
    * @default true
    */
   react?: VitePluginReactOptions | boolean;
+  /**
+   * Control build-time precompression of static assets (.br, .gz, .zst).
+   *
+   * - `'auto'` (default): enabled for Node.js production server targets,
+   *   disabled when deploying to edge platforms (Cloudflare Workers, Nitro)
+   *   that handle compression at the CDN layer.
+   * - `true`: always precompress, regardless of deployment target.
+   * - `false`: never precompress.
+   *
+   * Can also be disabled via `--no-precompress` CLI flag or
+   * `VINEXT_NO_PRECOMPRESS=1` environment variable.
+   */
+  precompress?: "auto" | boolean;
   /**
    * Experimental vinext-only feature flags.
    */
@@ -4434,6 +4448,50 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
         },
       },
     },
+    // Build-time precompression: generate .br, .gz, .zst for hashed assets.
+    // Runs after the client bundle is written so compressed variants are
+    // available for the production server's static file cache.
+    //
+    // Auto-skipped when targeting edge platforms (Cloudflare Workers, Nitro)
+    // that handle compression at the CDN layer — precompressing would waste
+    // build time and upload bandwidth for files the CDN compresses itself.
+    {
+      name: "vinext:precompress",
+      apply: "build",
+      enforce: "post",
+      writeBundle: {
+        sequential: true,
+        order: "post",
+        async handler(outputOptions) {
+          if (this.environment?.name !== "client") return;
+
+          // Resolve the precompress option: 'auto' (default) defers to
+          // deployment target detection; explicit true/false overrides.
+          const opt = options.precompress ?? "auto";
+          if (opt === false) return;
+          if (process.env.VINEXT_NO_PRECOMPRESS === "1") return;
+
+          if (opt === "auto" && (hasCloudflarePlugin || hasNitroPlugin)) return;
+
+          const outDir = outputOptions.dir;
+          if (!outDir) return;
+
+          // Only precompress hashed assets — public directory files use
+          // on-the-fly compression since they may change between deploys.
+          const assetsDir = path.join(outDir, "assets");
+          if (!fs.existsSync(assetsDir)) return;
+
+          const result = await precompressAssets(outDir);
+          if (result.filesCompressed > 0) {
+            const ratio = (
+              (1 - result.totalCompressedBytes / result.totalOriginalBytes) *
+              100
+            ).toFixed(1);
+            console.log(`  Precompressed ${result.filesCompressed} assets (${ratio}% smaller)`);
+          }
+        },
+      },
+    },
     // Cloudflare Workers production build integration:
     // After all environments are built, compute lazy chunks from the client
     // build manifest and inject globals into the worker entry.