@moostjs/vite 0.6.48 → 0.6.50

package/README.md

@@ -151,9 +151,18 @@ The three markers (`ssrOutlet`, `ssrState`, `ssrHead`) are plain string replacem
 
 Omit `ssrEntry` and Vite serves the app as a standard SPA. The production build still generates a server that serves static files and API routes — it just skips server-side rendering.
 
+### Compression and Caching
+
+Since `0.6.49`, in middleware mode the production build and the generated server handle static compression and caching by default:
+
+- **Precompression** (`precompress`, default on): after the client build, `.br` (brotli 11) and `.gz` (gzip 9) copies are written next to compressible files in `dist/client/` (js, css, html, svg, json, txt, xml, wasm — not source maps; files of at least 1 KiB, kept only when smaller). The server serves the copy the browser accepts, with `Content-Encoding` and `Vary: Accept-Encoding`. Tune with `{ brotli, gzip, threshold, include }` or disable with `false`.
+- **Cache headers** (`cacheControl`, default on): hashed files under `build.assetsDir` (`/assets/…`) get `public, max-age=31536000, immutable`; other static files and HTML pages (SPA fallback, SSR) get `no-cache`, and static files revalidate through their `ETag` (`304`). A `Cache-Control` set by your middleware, the app or the SSR render is never overridden. Override per class with `{ assets, assetsDir, files, html }` or disable with `false`.
+
+`createSSRServer({ precompressed, cacheControl })` overrides both at runtime. Dynamic responses are not covered: compress API responses in the app with `new MoostHttp({ compression: true })` and `@Compress()` (`@moostjs/event-http` 0.6.49+), and SSR HTML with a compression middleware in a custom server entry. Keep unhashed files out of `public/assets/`: they would be cached as immutable. Details: [Compression and Caching](https://moost.org/webapp/vite#compression-and-caching).
+
 ### Custom Server Entry
 
-By default, `vite build` auto-generates a minimal production server. If you need custom middleware (compression, auth, logging), provide your own server file:
+By default, `vite build` auto-generates a minimal production server. If you need custom middleware (compression of SSR responses, auth, logging), provide your own server file:
 
 ```ts
 moostVite({
@@ -170,7 +179,7 @@ moostVite({
 import { createSSRServer } from '@moostjs/vite/server'
 
 const app = await createSSRServer()
-// app.use(compression())
+// app.use(compression()) // SSR HTML; static files are precompressed, API uses MoostHttp({ compression })
 await app.listen()
 ```
 
@@ -270,6 +279,8 @@ The plugin injects a `__VITE_ID` decorator on `@Injectable` and `@Controller` cl
 | `ssrHead`          | `string`                                         | `'<!--ssr-head-->'`    | HTML placeholder for SSR-rendered `<head>` tags (place inside `<head>`)                                                                                                                                                                                                                                                                                     |
 | `serverEntry`      | `string`                                         | —                      | Custom production server entry file (e.g. `'./server.ts'`)                                                                                                                                                                                                                                                                                                  |
 | `ssrExternal`      | `string[]`                                       | —                      | Packages to keep external in the SSR build (middleware mode, `vite build` only). Concatenated with `cfg.ssr.external`. See [SSR Bundle Size](#ssr-bundle-size).                                                                                                                                                                                             |
+| `precompress`      | `boolean \| object`                              | `true`                 | Since `0.6.49`. Middleware mode: write `.br`/`.gz` copies of compressible client files after `vite build`; the generated server negotiates them. See [Compression and Caching](#compression-and-caching).                                                                                                                                                   |
+| `cacheControl`     | `boolean \| object`                              | `true`                 | Since `0.6.49`. Middleware mode: `Cache-Control` policy of the generated server (`immutable` hashed assets, `no-cache` for other files and HTML). See [Compression and Caching](#compression-and-caching).                                                                                                                                                  |
 | `ssrExternalCheck` | `boolean \| { packages?: (string \| RegExp)[] }` | `true`                 | Warn after the middleware-mode SSR build when an externalized package depends on a bundled shared-state package (`moost`, `@moostjs/*`, `wooks`, `@wooksjs/*`, `@prostojs/infact`/`mate`, `@atscript/*`), and at dev-server startup when one depends on a package the SSR runner inlines; `packages` watches more. See [SSR Bundle Size](#ssr-bundle-size). |
 
 Options marked "backend mode only" are ignored when `middleware: true` — the user's `vite.config.ts` controls build/server configuration in middleware mode.

package/dist/index.cjs

@@ -33,6 +33,10 @@ let magic_string = require("magic-string");
 magic_string = __toESM(magic_string);
 let node_module = require("node:module");
 let moost = require("moost");
+let node_fs_promises = require("node:fs/promises");
+let node_os = require("node:os");
+let node_util = require("node:util");
+let node_zlib = require("node:zlib");
 
 //#region packages/vite/src/utils.ts
 const PLUGIN_NAME = "moost-vite";
@@ -728,6 +732,91 @@ const toArray = (v) => Array.isArray(v) ? v : [v];
 	].join("\n");
 }
 
+//#endregion
+//#region packages/vite/src/precompress.ts
+const brotliAsync = (0, node_util.promisify)(node_zlib.brotliCompress);
+const gzipAsync = (0, node_util.promisify)(node_zlib.gzip);
+const DEFAULT_PRECOMPRESS_INCLUDE = /\.(?:m?js|cjs|css|html?|svg|json|webmanifest|txt|xml|wasm|ico|ttf|otf)$/i;
+/** Collects every file under `dir`, skipping dot entries except `.well-known` (as sirv serves them). */ async function collectFiles(dir, out = []) {
+	for (const entry of await (0, node_fs_promises.readdir)(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith(".") && entry.name !== ".well-known") continue;
+		const abs = (0, node_path.join)(dir, entry.name);
+		if (entry.isDirectory()) await collectFiles(abs, out);
+		else if (entry.isFile()) out.push(abs);
+	}
+	return out;
+}
+/**
+* Writes `.br` / `.gz` siblings for the compressible files under `dir` that are
+* at least `threshold` bytes, keeping a variant only when it is smaller than the
+* original. A sibling variant at least as new as its file (e.g. from another
+* compression plugin) is left untouched; an older, stale one is replaced.
+*/ async function precompressDir(dir, options = {}) {
+	const stats = {
+		files: 0,
+		brotli: 0,
+		gzip: 0
+	};
+	const useBrotli = options.brotli !== false;
+	const useGzip = options.gzip !== false;
+	if (!useBrotli && !useGzip || !(0, node_fs.existsSync)(dir)) return stats;
+	const threshold = options.threshold ?? 1024;
+	const include = options.include ?? DEFAULT_PRECOMPRESS_INCLUDE;
+	const queue = (await collectFiles(dir)).filter((abs) => {
+		const rel = (0, node_path.relative)(dir, abs).split(node_path.sep).join("/");
+		return !/\.(?:br|gz)$/.test(rel) && include.test(rel) && !options.exclude?.(rel);
+	});
+	const compressFile = async (abs) => {
+		const { size, mtimeMs } = await (0, node_fs_promises.stat)(abs);
+		if (size < threshold) return;
+		const data = await (0, node_fs_promises.readFile)(abs);
+		/**
+		* Writes one variant. A sibling at least as new as the source was written
+		* by another tool for this build and is kept; an older one is stale (an
+		* earlier build into a non-emptied outDir) and is replaced — or removed
+		* when the new variant would not be smaller.
+		*/ const variant = async (ext, encode) => {
+			const target = abs + ext;
+			const sibling = await (0, node_fs_promises.stat)(target).catch(() => void 0);
+			if (sibling && sibling.mtimeMs >= mtimeMs) return false;
+			const encoded = await encode();
+			if (encoded.length >= size) {
+				if (sibling) await (0, node_fs_promises.rm)(target);
+				return false;
+			}
+			await (0, node_fs_promises.writeFile)(target, encoded);
+			return true;
+		};
+		const [br, gz] = await Promise.all([useBrotli && variant(".br", () => brotliAsync(data, { params: {
+			[node_zlib.constants.BROTLI_PARAM_QUALITY]: node_zlib.constants.BROTLI_MAX_QUALITY,
+			[node_zlib.constants.BROTLI_PARAM_SIZE_HINT]: size
+		} })), useGzip && variant(".gz", () => gzipAsync(data, { level: 9 }))]);
+		stats.brotli += br ? 1 : 0;
+		stats.gzip += gz ? 1 : 0;
+		stats.files += br || gz ? 1 : 0;
+	};
+	let next = 0;
+	const workers = Array.from({ length: Math.min((0, node_os.availableParallelism)(), queue.length) }, async () => {
+		while (next < queue.length) await compressFile(queue[next++]);
+	});
+	await Promise.all(workers);
+	return stats;
+}
+
+//#endregion
+//#region packages/vite/src/prod-static.ts
+/** Resolves which precompressed variants to serve (build-time value + runtime override). */ function resolvePrecompressed(baked, override) {
+	const opts = override ?? baked ?? true;
+	if (typeof opts === "boolean") return {
+		brotli: opts,
+		gzip: opts
+	};
+	return {
+		brotli: opts.brotli !== false,
+		gzip: opts.gzip !== false
+	};
+}
+
 //#endregion
 //#region packages/vite/src/moost-vite.ts
 /**
@@ -798,6 +887,17 @@ function moostVite(options) {
 	const ssrOutlet = options.ssrOutlet || DEFAULT_SSR_OUTLET;
 	const ssrState = options.ssrState || DEFAULT_SSR_STATE;
 	const ssrHead = options.ssrHead || DEFAULT_SSR_HEAD;
+	const precompress = options.precompress ?? true;
+	/** The variants the generated prod server negotiates (`__MOOST_PRECOMPRESS__`). */ const precompressedVariants = precompress === false ? false : resolvePrecompressed(void 0, precompress);
+	/** The cache policy baked into the prod server (`__MOOST_CACHE_CONTROL__`). */ const bakedCacheControl = (cfg) => {
+		const cacheControl = options.cacheControl ?? true;
+		if (cacheControl === false) return false;
+		const custom = cacheControl === true ? {} : cacheControl;
+		return {
+			...custom,
+			assetsDir: custom.assetsDir ?? cfg.environments?.client?.build?.assetsDir ?? cfg.build?.assetsDir ?? "assets"
+		};
+	};
 	const splitCheckPatterns = compilePackagePatterns(typeof options.ssrExternalCheck === "object" ? options.ssrExternalCheck.packages : void 0);
 	/**
 	* Boot-identity stamps (dev-only "mongrel state" diagnostic — a stale pipeline
@@ -950,7 +1050,9 @@ function moostVite(options) {
 					__MOOST_SSR_ENTRY__: "undefined",
 					__MOOST_SSR_OUTLET__: JSON.stringify(ssrOutlet),
 					__MOOST_SSR_STATE__: JSON.stringify(ssrState),
-					__MOOST_SSR_HEAD__: JSON.stringify(ssrHead)
+					__MOOST_SSR_HEAD__: JSON.stringify(ssrHead),
+					__MOOST_PRECOMPRESS__: JSON.stringify(precompressedVariants),
+					__MOOST_CACHE_CONTROL__: JSON.stringify(bakedCacheControl(cfg))
 				};
 				const ssrInput = {
 					server: options.serverEntry || generatedServerEntry(cfg.root),
@@ -1033,6 +1135,20 @@ function moostVite(options) {
 				}
 			};
 		},
+		buildApp: {
+			order: "post",
+			async handler(builder) {
+				const client = builder.environments.client;
+				if (!options.middleware || precompress === false || !client?.isBuilt) return;
+				const { root, build } = client.config;
+				if (build.write === false) return;
+				const result = await precompressDir((0, node_path.resolve)(root, build.outDir), {
+					...precompress === true ? {} : precompress,
+					exclude: options.ssrEntry ? (rel) => rel === "index.html" : void 0
+				});
+				if (result.files > 0) client.logger.info(`[${PLUGIN_NAME}] precompressed ${result.files} client files (${result.brotli} .br, ${result.gzip} .gz)`);
+			}
+		},
 		configResolved(config) {
 			config.__moostViteOptions = {
 				entry: options.entry,

package/dist/index.d.ts

@@ -1,6 +1,56 @@
 import { PluginOption } from 'vite';
 import { IncomingMessage } from 'node:http';
 
+/**
+ * Build-time precompression of the client build (`precompress` plugin option).
+ * Writes `<file>.br` / `<file>.gz` siblings the production server negotiates.
+ */
+interface TPrecompressOptions {
+    /** Write brotli (`.br`, quality 11) siblings. Default: `true`. */
+    brotli?: boolean;
+    /** Write gzip (`.gz`, level 9) siblings. Default: `true`. */
+    gzip?: boolean;
+    /** Skip files smaller than this many bytes. Default: `1024`. */
+    threshold?: number;
+    /**
+     * Which files to compress, tested against the path relative to the client
+     * build root. Default: text-like assets — js/mjs/cjs, css, html, svg, json,
+     * webmanifest, txt, xml, wasm, ico, ttf, otf. Images and already compressed
+     * formats (png, jpg, webp, woff/woff2, …) gain nothing; source maps are only
+     * fetched by devtools and would dominate the build time at brotli 11.
+     */
+    include?: RegExp;
+}
+
+/**
+ * `Cache-Control` policy of the generated production server. Each value is a
+ * full `Cache-Control` header value; `false` sends no `Cache-Control` for that
+ * class of responses. A `Cache-Control` already set on the response (by a user
+ * middleware, the app or the SSR render's `headers`) is never overridden.
+ */
+interface TCacheControlOptions {
+    /**
+     * Files under the hashed assets directory (`/<assetsDir>/…`). Vite puts a
+     * content hash in every file name there, so they never change.
+     * Default: `'public, max-age=31536000, immutable'`.
+     */
+    assets?: string | false;
+    /**
+     * The hashed assets directory, relative to the client build root.
+     * Default: the client `build.assetsDir` (`'assets'`). An empty value (assets
+     * emitted at the build root) leaves no file in the `assets` class: hashed and
+     * unhashed files cannot be told apart there, so all of them get `files`.
+     */
+    assetsDir?: string;
+    /**
+     * Every other static file (files copied from `public/`, `favicon.ico`, …).
+     * Revalidated through the `ETag`. Default: `'no-cache'`.
+     */
+    files?: string | false;
+    /** HTML pages: the SPA fallback and SSR-rendered pages. Default: `'no-cache'`. */
+    html?: string | false;
+}
+
 interface TMoostViteDevOptions {
     /**
      * The entry file for the application.
@@ -202,6 +252,45 @@ interface TMoostViteDevOptions {
      * Default: `true`. Set `false` to silence both checks.
      */
     ssrExternalCheck?: boolean | TSSRExternalCheckOptions;
+    /**
+     * Precompress the client build (middleware mode, `vite build`): after the
+     * client environment is built, write a brotli (`.br`, quality 11) and a gzip
+     * (`.gz`, level 9) sibling next to every compressible file (js, css, html,
+     * svg, json, txt, xml, wasm, … — not source maps, images or woff fonts) of at least
+     * 1 KiB, keeping a variant only when it is smaller than the original. Files
+     * copied from `public/` are included.
+     *
+     * The generated production server serves the variant the client accepts
+     * (`Accept-Encoding`) with `Content-Encoding` and `Vary: Accept-Encoding`.
+     * Costs some build time (brotli 11 is slow but runs once) and dist size.
+     *
+     * Runs as a `buildApp` hook after the app build, so it also applies when you
+     * provide your own `builder.buildApp`. Pass `{ brotli, gzip, threshold,
+     * include }` to tune it.
+     *
+     * Default: `true`. Set `false` to skip it (and to stop the generated server
+     * from looking for variants).
+     */
+    precompress?: boolean | TPrecompressOptions;
+    /**
+     * `Cache-Control` policy baked into the generated production server
+     * (middleware mode):
+     * - hashed files under the client `build.assetsDir` (`/assets/…`):
+     *   `public, max-age=31536000, immutable`;
+     * - every other static file (`public/` copies, `favicon.ico`, …): `no-cache`,
+     *   revalidated through the `ETag` (`304 Not Modified`);
+     * - HTML (SPA fallback, SSR pages): `no-cache`.
+     *
+     * A `Cache-Control` set by a user middleware, the app or the SSR render's
+     * `headers` is never overridden. Keep unhashed files out of `public/assets/`
+     * — they would be cached as immutable. Override per class with
+     * `{ assets, files, html }` (a header value, or `false` for none) or move the
+     * hashed directory with `assetsDir`; `createSSRServer({ cacheControl })`
+     * overrides it at runtime.
+     *
+     * Default: `true`. Set `false` to send no `Cache-Control` from the server.
+     */
+    cacheControl?: boolean | TCacheControlOptions;
 }
 /** Extra packages the SSR split check should watch on top of its defaults. */
 interface TSSRExternalCheckOptions {
@@ -253,4 +342,4 @@ interface TSSRRenderContext {
 type TSSRRender = (url: string, ctx?: TSSRRenderContext) => Promise<TSSRRenderResult> | TSSRRenderResult;
 
 export { moostVite };
-export type { TMoostViteDevOptions, TSSRRender, TSSRRenderContext, TSSRRenderResult };
+export type { TCacheControlOptions, TMoostViteDevOptions, TPrecompressOptions, TSSRRender, TSSRRenderContext, TSSRRenderResult };

package/dist/index.mjs

@@ -1,9 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { createServerModuleRunner } from "vite";
 import MagicString from "magic-string";
 import { builtinModules } from "node:module";
 import { Moost, clearGlobalWooks, createLogger, disposeInstances, getMoostInfact, getMoostMate } from "moost";
+import { readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { availableParallelism } from "node:os";
+import { promisify } from "node:util";
+import { brotliCompress, constants, gzip } from "node:zlib";
 
 //#region packages/vite/src/utils.ts
 const PLUGIN_NAME = "moost-vite";
@@ -699,6 +703,91 @@ const toArray = (v) => Array.isArray(v) ? v : [v];
 	].join("\n");
 }
 
+//#endregion
+//#region packages/vite/src/precompress.ts
+const brotliAsync = promisify(brotliCompress);
+const gzipAsync = promisify(gzip);
+const DEFAULT_PRECOMPRESS_INCLUDE = /\.(?:m?js|cjs|css|html?|svg|json|webmanifest|txt|xml|wasm|ico|ttf|otf)$/i;
+/** Collects every file under `dir`, skipping dot entries except `.well-known` (as sirv serves them). */ async function collectFiles(dir, out = []) {
+	for (const entry of await readdir(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith(".") && entry.name !== ".well-known") continue;
+		const abs = join(dir, entry.name);
+		if (entry.isDirectory()) await collectFiles(abs, out);
+		else if (entry.isFile()) out.push(abs);
+	}
+	return out;
+}
+/**
+* Writes `.br` / `.gz` siblings for the compressible files under `dir` that are
+* at least `threshold` bytes, keeping a variant only when it is smaller than the
+* original. A sibling variant at least as new as its file (e.g. from another
+* compression plugin) is left untouched; an older, stale one is replaced.
+*/ async function precompressDir(dir, options = {}) {
+	const stats = {
+		files: 0,
+		brotli: 0,
+		gzip: 0
+	};
+	const useBrotli = options.brotli !== false;
+	const useGzip = options.gzip !== false;
+	if (!useBrotli && !useGzip || !existsSync(dir)) return stats;
+	const threshold = options.threshold ?? 1024;
+	const include = options.include ?? DEFAULT_PRECOMPRESS_INCLUDE;
+	const queue = (await collectFiles(dir)).filter((abs) => {
+		const rel = relative(dir, abs).split(sep).join("/");
+		return !/\.(?:br|gz)$/.test(rel) && include.test(rel) && !options.exclude?.(rel);
+	});
+	const compressFile = async (abs) => {
+		const { size, mtimeMs } = await stat(abs);
+		if (size < threshold) return;
+		const data = await readFile(abs);
+		/**
+		* Writes one variant. A sibling at least as new as the source was written
+		* by another tool for this build and is kept; an older one is stale (an
+		* earlier build into a non-emptied outDir) and is replaced — or removed
+		* when the new variant would not be smaller.
+		*/ const variant = async (ext, encode) => {
+			const target = abs + ext;
+			const sibling = await stat(target).catch(() => void 0);
+			if (sibling && sibling.mtimeMs >= mtimeMs) return false;
+			const encoded = await encode();
+			if (encoded.length >= size) {
+				if (sibling) await rm(target);
+				return false;
+			}
+			await writeFile(target, encoded);
+			return true;
+		};
+		const [br, gz] = await Promise.all([useBrotli && variant(".br", () => brotliAsync(data, { params: {
+			[constants.BROTLI_PARAM_QUALITY]: constants.BROTLI_MAX_QUALITY,
+			[constants.BROTLI_PARAM_SIZE_HINT]: size
+		} })), useGzip && variant(".gz", () => gzipAsync(data, { level: 9 }))]);
+		stats.brotli += br ? 1 : 0;
+		stats.gzip += gz ? 1 : 0;
+		stats.files += br || gz ? 1 : 0;
+	};
+	let next = 0;
+	const workers = Array.from({ length: Math.min(availableParallelism(), queue.length) }, async () => {
+		while (next < queue.length) await compressFile(queue[next++]);
+	});
+	await Promise.all(workers);
+	return stats;
+}
+
+//#endregion
+//#region packages/vite/src/prod-static.ts
+/** Resolves which precompressed variants to serve (build-time value + runtime override). */ function resolvePrecompressed(baked, override) {
+	const opts = override ?? baked ?? true;
+	if (typeof opts === "boolean") return {
+		brotli: opts,
+		gzip: opts
+	};
+	return {
+		brotli: opts.brotli !== false,
+		gzip: opts.gzip !== false
+	};
+}
+
 //#endregion
 //#region packages/vite/src/moost-vite.ts
 /**
@@ -767,6 +856,17 @@ function moostVite(options) {
 	const ssrOutlet = options.ssrOutlet || DEFAULT_SSR_OUTLET;
 	const ssrState = options.ssrState || DEFAULT_SSR_STATE;
 	const ssrHead = options.ssrHead || DEFAULT_SSR_HEAD;
+	const precompress = options.precompress ?? true;
+	/** The variants the generated prod server negotiates (`__MOOST_PRECOMPRESS__`). */ const precompressedVariants = precompress === false ? false : resolvePrecompressed(void 0, precompress);
+	/** The cache policy baked into the prod server (`__MOOST_CACHE_CONTROL__`). */ const bakedCacheControl = (cfg) => {
+		const cacheControl = options.cacheControl ?? true;
+		if (cacheControl === false) return false;
+		const custom = cacheControl === true ? {} : cacheControl;
+		return {
+			...custom,
+			assetsDir: custom.assetsDir ?? cfg.environments?.client?.build?.assetsDir ?? cfg.build?.assetsDir ?? "assets"
+		};
+	};
 	const splitCheckPatterns = compilePackagePatterns(typeof options.ssrExternalCheck === "object" ? options.ssrExternalCheck.packages : void 0);
 	/**
 	* Boot-identity stamps (dev-only "mongrel state" diagnostic — a stale pipeline
@@ -919,7 +1019,9 @@ function moostVite(options) {
 					__MOOST_SSR_ENTRY__: "undefined",
 					__MOOST_SSR_OUTLET__: JSON.stringify(ssrOutlet),
 					__MOOST_SSR_STATE__: JSON.stringify(ssrState),
-					__MOOST_SSR_HEAD__: JSON.stringify(ssrHead)
+					__MOOST_SSR_HEAD__: JSON.stringify(ssrHead),
+					__MOOST_PRECOMPRESS__: JSON.stringify(precompressedVariants),
+					__MOOST_CACHE_CONTROL__: JSON.stringify(bakedCacheControl(cfg))
 				};
 				const ssrInput = {
 					server: options.serverEntry || generatedServerEntry(cfg.root),
@@ -1002,6 +1104,20 @@ function moostVite(options) {
 				}
 			};
 		},
+		buildApp: {
+			order: "post",
+			async handler(builder) {
+				const client = builder.environments.client;
+				if (!options.middleware || precompress === false || !client?.isBuilt) return;
+				const { root, build } = client.config;
+				if (build.write === false) return;
+				const result = await precompressDir(resolve(root, build.outDir), {
+					...precompress === true ? {} : precompress,
+					exclude: options.ssrEntry ? (rel) => rel === "index.html" : void 0
+				});
+				if (result.files > 0) client.logger.info(`[${PLUGIN_NAME}] precompressed ${result.files} client files (${result.brotli} .br, ${result.gzip} .gz)`);
+			}
+		},
 		configResolved(config) {
 			config.__moostViteOptions = {
 				entry: options.entry,

package/dist/prod-server.cjs

@@ -1,7 +1,152 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 let node_events = require("node:events");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
 let moost = require("moost");
 
+//#region packages/vite/src/prod-static.ts
+const DEFAULT_ASSETS_CACHE_CONTROL = "public, max-age=31536000, immutable";
+const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
+/**
+* Resolves the cache policy from the build-time value and a runtime override:
+* an override object is merged over the baked object (or the defaults when the
+* build disabled it), `true` keeps the baked policy, `false` disables it.
+*/ function resolveCacheControl(baked, override) {
+	if (override === false || override === void 0 && baked === false) return null;
+	const opts = {
+		...baked || void 0,
+		...typeof override === "object" ? override : void 0
+	};
+	const assetsDir = (opts.assetsDir ?? "assets").replace(/^\/+|\/+$/g, "");
+	return {
+		assets: opts.assets ?? DEFAULT_ASSETS_CACHE_CONTROL,
+		assetsPrefix: assetsDir ? `/${assetsDir}/` : null,
+		files: opts.files ?? DEFAULT_REVALIDATE_CACHE_CONTROL,
+		html: opts.html ?? DEFAULT_REVALIDATE_CACHE_CONTROL
+	};
+}
+/** Resolves which precompressed variants to serve (build-time value + runtime override). */ function resolvePrecompressed(baked, override) {
+	const opts = override ?? baked ?? true;
+	if (typeof opts === "boolean") return {
+		brotli: opts,
+		gzip: opts
+	};
+	return {
+		brotli: opts.brotli !== false,
+		gzip: opts.gzip !== false
+	};
+}
+/** The decoded pathname of a request url, the way sirv looks files up. */ function requestPathname(url) {
+	const end = url.search(/[?#]/);
+	const pathname = end === -1 ? url : url.slice(0, end);
+	if (!pathname.includes("%")) return pathname;
+	try {
+		return decodeURI(pathname);
+	} catch {
+		return pathname;
+	}
+}
+/**
+* The root `index.html` (and precompressed siblings) is the SPA/SSR template:
+* it is never served as a static file, but by the SPA/SSR fallback (in SSR mode
+* a raw template would leak its unfilled `<!--ssr-outlet-->` placeholders).
+* sirv drops one trailing slash before its lookup, so `/index.html/` matches too.
+*/ function isIndexTemplatePath(pathname) {
+	return /^\/index\.html(?:\.br|\.gz)?\/?$/.test(pathname);
+}
+/**
+* Sets a header unless the response already carries it. Returns a restore
+* callback that removes it again only if it still holds the value set here.
+*/ function presetHeader(res, name, value) {
+	if (res.hasHeader(name)) return () => {};
+	res.setHeader(name, value);
+	return () => {
+		if (res.getHeader(name) === value) res.removeHeader(name);
+	};
+}
+/**
+* Adds `Accept-Encoding` to the response's `Vary`, keeping the tokens already
+* there. Returns a restore callback that puts the previous value back.
+*/ function varyAcceptEncoding(res) {
+	const prev = res.getHeader("Vary");
+	if (prev !== void 0 && /(?:^|,)\s*(?:\*|accept-encoding)\s*(?:,|$)/i.test(String(prev))) return () => {};
+	const next = prev === void 0 ? "Accept-Encoding" : `${String(prev)}, Accept-Encoding`;
+	res.setHeader("Vary", next);
+	return () => {
+		if (res.getHeader("Vary") === next) if (prev === void 0) res.removeHeader("Vary");
+		else res.setHeader("Vary", prev);
+	};
+}
+/** Reads the precompressed siblings of the SPA shell (`index.html.br` / `.gz`), when enabled. */ async function loadSpaShell(clientDir, html, variants) {
+	const read = (enabled, ext) => enabled ? (0, node_fs_promises.readFile)((0, node_path.join)(clientDir, `index.html${ext}`)).catch(() => void 0) : void 0;
+	const [br, gzip] = await Promise.all([read(variants.brotli, ".br"), read(variants.gzip, ".gz")]);
+	return {
+		html,
+		br,
+		gzip
+	};
+}
+/** Sends the SPA shell for client-side routing, precompressed when the client accepts it. */ function sendSpaShell(req, res, shell, cache) {
+	res.statusCode = 200;
+	res.setHeader("Content-Type", "text/html");
+	if (cache?.html) presetHeader(res, "Cache-Control", cache.html);
+	let body = shell.html;
+	if (shell.br || shell.gzip) {
+		varyAcceptEncoding(res);
+		const accept = req.headers["accept-encoding"] || "";
+		const variant = shell.br && /\b(?:br|brotli)\b/i.test(accept) ? {
+			encoding: "br",
+			data: shell.br
+		} : shell.gzip && /\bgzip\b/i.test(accept) ? {
+			encoding: "gzip",
+			data: shell.gzip
+		} : void 0;
+		if (variant) {
+			res.setHeader("Content-Encoding", variant.encoding);
+			body = variant.data;
+		}
+	}
+	res.end(body);
+}
+/**
+* Static file serving (sirv) with the cache policy and the precompressed
+* variants; requests that match no file — and the root `index.html` template —
+* go to `servePage` (SSR render or SPA shell).
+*/ async function createStaticHandler(clientDir, variants, cache, servePage) {
+	const { default: sirv } = await import("sirv");
+	const negotiate = variants.brotli || variants.gzip;
+	/** The `Vary` each response should carry: sirv overwrites it with a bare `Accept-Encoding`. */ const varyOf = /* @__PURE__ */ new WeakMap();
+	const serve = sirv(clientDir, {
+		extensions: [],
+		etag: true,
+		brotli: variants.brotli,
+		gzip: variants.gzip,
+		setHeaders: (res) => {
+			const vary = varyOf.get(res);
+			if (vary) res.setHeader("Vary", vary);
+		}
+	});
+	return (req, res) => {
+		const pathname = requestPathname(req.url || "/");
+		if (isIndexTemplatePath(pathname)) {
+			servePage(req, res);
+			return;
+		}
+		const restore = [];
+		const cacheControl = cache && (cache.assetsPrefix && pathname.startsWith(cache.assetsPrefix) ? cache.assets : cache.files);
+		if (cacheControl) restore.push(presetHeader(res, "Cache-Control", cacheControl));
+		if (negotiate) {
+			restore.push(varyAcceptEncoding(res));
+			varyOf.set(res, String(res.getHeader("Vary")));
+		}
+		serve(req, res, () => {
+			for (const undo of restore) undo();
+			servePage(req, res);
+		});
+	};
+}
+
+//#endregion
 //#region packages/vite/src/utils.ts
 const PLUGIN_NAME = "moost-vite";
 const DEFAULT_SSR_OUTLET = "<!--ssr-outlet-->";
@@ -160,6 +305,8 @@ async function createSSRServer(options) {
 	const ssrHead = opts.ssrHead || (__MOOST_SSR_HEAD__ !== void 0 ? __MOOST_SSR_HEAD__ : DEFAULT_SSR_HEAD);
 	const prefixes = normalizePrefixes(opts.prefix ?? __MOOST_PREFIX__);
 	const ssrForwarding = opts.ssrFetchForwarding ?? __MOOST_SSR_FORWARDING__ ?? true;
+	const variants = resolvePrecompressed(__MOOST_PRECOMPRESS__, opts.precompressed);
+	const cache = resolveCacheControl(__MOOST_CACHE_CONTROL__, opts.cacheControl);
 	const defaultPort = opts.port || Number(process.env.PORT) || 3e3;
 	const defaultHost = opts.host ?? process.env.HOST;
 	const template = await fs.readFile(path.resolve(clientDir, "index.html"), "utf8");
@@ -197,42 +344,36 @@ async function createSSRServer(options) {
 	}
 	MoostHttp.prototype.listen = origListen;
 	if (enableLocalFetch && moostHttpRef.instance) enableLocalFetch(moostHttpRef.instance);
-	const sirv = (await import("sirv")).default;
-	const serve = sirv(path.resolve(clientDir), { extensions: [] });
-	const serveStatic = (req, res) => {
-		const url = req.url || "/";
-		serve(req, res, async () => {
-			if (req.method !== "GET") {
-				res.statusCode = 404;
-				res.end();
-				return;
-			}
-			try {
-				if (render) {
-					const result = await renderSSRPage({
-						render,
-						url,
-						req,
-						res,
-						http: ssrForwarding ? moostHttpRef.instance : null
-					});
-					sendSSRResponse(res, template, {
-						ssrOutlet,
-						ssrState,
-						ssrHead
-					}, result);
-				} else {
-					res.statusCode = 200;
-					res.setHeader("Content-Type", "text/html");
-					res.end(template);
-				}
-			} catch (error) {
-				console.error(error);
-				res.statusCode = 500;
-				res.end(error.message);
-			}
-		});
+	const spaShell = render ? { html: template } : await loadSpaShell(clientDir, template, variants);
+	/** HTML page fallback: SSR render or the SPA shell. */ const servePage = async (req, res) => {
+		if (req.method !== "GET") {
+			res.statusCode = 404;
+			res.end();
+			return;
+		}
+		try {
+			if (render) {
+				const result = await renderSSRPage({
+					render,
+					url: req.url || "/",
+					req,
+					res,
+					http: ssrForwarding ? moostHttpRef.instance : null
+				});
+				if (cache?.html) presetHeader(res, "Cache-Control", cache.html);
+				sendSSRResponse(res, template, {
+					ssrOutlet,
+					ssrState,
+					ssrHead
+				}, result);
+			} else sendSpaShell(req, res, spaShell, cache);
+		} catch (error) {
+			console.error(error);
+			res.statusCode = 500;
+			res.end(error.message);
+		}
 	};
+	const serveStatic = await createStaticHandler(path.resolve(clientDir), variants, cache, (req, res) => void servePage(req, res));
 	return {
 		use(mw) {
 			userMiddlewares.push(mw);

package/dist/prod-server.d.ts

@@ -1,6 +1,42 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { Server } from 'node:net';
 
+/**
+ * `Cache-Control` policy of the generated production server. Each value is a
+ * full `Cache-Control` header value; `false` sends no `Cache-Control` for that
+ * class of responses. A `Cache-Control` already set on the response (by a user
+ * middleware, the app or the SSR render's `headers`) is never overridden.
+ */
+interface TCacheControlOptions {
+    /**
+     * Files under the hashed assets directory (`/<assetsDir>/…`). Vite puts a
+     * content hash in every file name there, so they never change.
+     * Default: `'public, max-age=31536000, immutable'`.
+     */
+    assets?: string | false;
+    /**
+     * The hashed assets directory, relative to the client build root.
+     * Default: the client `build.assetsDir` (`'assets'`). An empty value (assets
+     * emitted at the build root) leaves no file in the `assets` class: hashed and
+     * unhashed files cannot be told apart there, so all of them get `files`.
+     */
+    assetsDir?: string;
+    /**
+     * Every other static file (files copied from `public/`, `favicon.ico`, …).
+     * Revalidated through the `ETag`. Default: `'no-cache'`.
+     */
+    files?: string | false;
+    /** HTML pages: the SPA fallback and SSR-rendered pages. Default: `'no-cache'`. */
+    html?: string | false;
+}
+/** Precompressed sibling variants the production server negotiates. */
+interface TPrecompressedOptions {
+    /** Serve `<file>.br` to clients that accept brotli. Default: `true`. */
+    brotli?: boolean;
+    /** Serve `<file>.gz` to clients that accept gzip. Default: `true`. */
+    gzip?: boolean;
+}
+
 /**
  * The value an SSR `render(url)` function may return. Only `html` is required;
  * every other field is optional, so a render returning `{ html }` (or
@@ -74,6 +110,24 @@ interface TSSRServerOptions {
      * Set to `false` to keep SSR self-calls anonymous. Default: `true`.
      */
     ssrFetchForwarding?: boolean;
+    /**
+     * Production only. Serve the precompressed `<file>.br` / `<file>.gz` siblings
+     * written by the plugin's `precompress` build step to clients that accept
+     * them (`Content-Encoding` + `Vary: Accept-Encoding`). Applies to static
+     * files and the SPA fallback page.
+     * Default: baked from the plugin's `precompress` option (on).
+     */
+    precompressed?: boolean | TPrecompressedOptions;
+    /**
+     * Production only. `Cache-Control` policy: hashed files under the assets
+     * directory are `immutable` for a year, other static files and HTML pages
+     * are `no-cache` (revalidated through the `ETag`). A `Cache-Control` already
+     * set by a middleware, the app or the SSR render is never overridden.
+     * An object is merged over the plugin's `cacheControl` option; `false` sends
+     * no `Cache-Control` from the server.
+     * Default: baked from the plugin's `cacheControl` option (on).
+     */
+    cacheControl?: boolean | TCacheControlOptions;
 }
 interface TSSRServer {
     /** Add Connect-compatible middleware (runs in both dev and prod) */
@@ -89,4 +143,4 @@ interface TSSRServer {
 declare function createSSRServer(options?: TSSRServerOptions): Promise<TSSRServer>;
 
 export { createSSRServer };
-export type { TSSRRender, TSSRRenderContext, TSSRRenderResult, TSSRServer, TSSRServerOptions };
+export type { TCacheControlOptions, TPrecompressedOptions, TSSRRender, TSSRRenderContext, TSSRRenderResult, TSSRServer, TSSRServerOptions };

package/dist/prod-server.mjs

@@ -1,8 +1,153 @@
 import { once } from "node:events";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
 import "node:fs";
 import "node:module";
 import { createLogger } from "moost";
 
+//#region packages/vite/src/prod-static.ts
+const DEFAULT_ASSETS_CACHE_CONTROL = "public, max-age=31536000, immutable";
+const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
+/**
+* Resolves the cache policy from the build-time value and a runtime override:
+* an override object is merged over the baked object (or the defaults when the
+* build disabled it), `true` keeps the baked policy, `false` disables it.
+*/ function resolveCacheControl(baked, override) {
+	if (override === false || override === void 0 && baked === false) return null;
+	const opts = {
+		...baked || void 0,
+		...typeof override === "object" ? override : void 0
+	};
+	const assetsDir = (opts.assetsDir ?? "assets").replace(/^\/+|\/+$/g, "");
+	return {
+		assets: opts.assets ?? DEFAULT_ASSETS_CACHE_CONTROL,
+		assetsPrefix: assetsDir ? `/${assetsDir}/` : null,
+		files: opts.files ?? DEFAULT_REVALIDATE_CACHE_CONTROL,
+		html: opts.html ?? DEFAULT_REVALIDATE_CACHE_CONTROL
+	};
+}
+/** Resolves which precompressed variants to serve (build-time value + runtime override). */ function resolvePrecompressed(baked, override) {
+	const opts = override ?? baked ?? true;
+	if (typeof opts === "boolean") return {
+		brotli: opts,
+		gzip: opts
+	};
+	return {
+		brotli: opts.brotli !== false,
+		gzip: opts.gzip !== false
+	};
+}
+/** The decoded pathname of a request url, the way sirv looks files up. */ function requestPathname(url) {
+	const end = url.search(/[?#]/);
+	const pathname = end === -1 ? url : url.slice(0, end);
+	if (!pathname.includes("%")) return pathname;
+	try {
+		return decodeURI(pathname);
+	} catch {
+		return pathname;
+	}
+}
+/**
+* The root `index.html` (and precompressed siblings) is the SPA/SSR template:
+* it is never served as a static file, but by the SPA/SSR fallback (in SSR mode
+* a raw template would leak its unfilled `<!--ssr-outlet-->` placeholders).
+* sirv drops one trailing slash before its lookup, so `/index.html/` matches too.
+*/ function isIndexTemplatePath(pathname) {
+	return /^\/index\.html(?:\.br|\.gz)?\/?$/.test(pathname);
+}
+/**
+* Sets a header unless the response already carries it. Returns a restore
+* callback that removes it again only if it still holds the value set here.
+*/ function presetHeader(res, name, value) {
+	if (res.hasHeader(name)) return () => {};
+	res.setHeader(name, value);
+	return () => {
+		if (res.getHeader(name) === value) res.removeHeader(name);
+	};
+}
+/**
+* Adds `Accept-Encoding` to the response's `Vary`, keeping the tokens already
+* there. Returns a restore callback that puts the previous value back.
+*/ function varyAcceptEncoding(res) {
+	const prev = res.getHeader("Vary");
+	if (prev !== void 0 && /(?:^|,)\s*(?:\*|accept-encoding)\s*(?:,|$)/i.test(String(prev))) return () => {};
+	const next = prev === void 0 ? "Accept-Encoding" : `${String(prev)}, Accept-Encoding`;
+	res.setHeader("Vary", next);
+	return () => {
+		if (res.getHeader("Vary") === next) if (prev === void 0) res.removeHeader("Vary");
+		else res.setHeader("Vary", prev);
+	};
+}
+/** Reads the precompressed siblings of the SPA shell (`index.html.br` / `.gz`), when enabled. */ async function loadSpaShell(clientDir, html, variants) {
+	const read = (enabled, ext) => enabled ? readFile(join(clientDir, `index.html${ext}`)).catch(() => void 0) : void 0;
+	const [br, gzip] = await Promise.all([read(variants.brotli, ".br"), read(variants.gzip, ".gz")]);
+	return {
+		html,
+		br,
+		gzip
+	};
+}
+/** Sends the SPA shell for client-side routing, precompressed when the client accepts it. */ function sendSpaShell(req, res, shell, cache) {
+	res.statusCode = 200;
+	res.setHeader("Content-Type", "text/html");
+	if (cache?.html) presetHeader(res, "Cache-Control", cache.html);
+	let body = shell.html;
+	if (shell.br || shell.gzip) {
+		varyAcceptEncoding(res);
+		const accept = req.headers["accept-encoding"] || "";
+		const variant = shell.br && /\b(?:br|brotli)\b/i.test(accept) ? {
+			encoding: "br",
+			data: shell.br
+		} : shell.gzip && /\bgzip\b/i.test(accept) ? {
+			encoding: "gzip",
+			data: shell.gzip
+		} : void 0;
+		if (variant) {
+			res.setHeader("Content-Encoding", variant.encoding);
+			body = variant.data;
+		}
+	}
+	res.end(body);
+}
+/**
+* Static file serving (sirv) with the cache policy and the precompressed
+* variants; requests that match no file — and the root `index.html` template —
+* go to `servePage` (SSR render or SPA shell).
+*/ async function createStaticHandler(clientDir, variants, cache, servePage) {
+	const { default: sirv } = await import("sirv");
+	const negotiate = variants.brotli || variants.gzip;
+	/** The `Vary` each response should carry: sirv overwrites it with a bare `Accept-Encoding`. */ const varyOf = /* @__PURE__ */ new WeakMap();
+	const serve = sirv(clientDir, {
+		extensions: [],
+		etag: true,
+		brotli: variants.brotli,
+		gzip: variants.gzip,
+		setHeaders: (res) => {
+			const vary = varyOf.get(res);
+			if (vary) res.setHeader("Vary", vary);
+		}
+	});
+	return (req, res) => {
+		const pathname = requestPathname(req.url || "/");
+		if (isIndexTemplatePath(pathname)) {
+			servePage(req, res);
+			return;
+		}
+		const restore = [];
+		const cacheControl = cache && (cache.assetsPrefix && pathname.startsWith(cache.assetsPrefix) ? cache.assets : cache.files);
+		if (cacheControl) restore.push(presetHeader(res, "Cache-Control", cacheControl));
+		if (negotiate) {
+			restore.push(varyAcceptEncoding(res));
+			varyOf.set(res, String(res.getHeader("Vary")));
+		}
+		serve(req, res, () => {
+			for (const undo of restore) undo();
+			servePage(req, res);
+		});
+	};
+}
+
+//#endregion
 //#region packages/vite/src/utils.ts
 const PLUGIN_NAME = "moost-vite";
 const DEFAULT_SSR_OUTLET = "<!--ssr-outlet-->";
@@ -161,6 +306,8 @@ async function createSSRServer(options) {
 	const ssrHead = opts.ssrHead || (__MOOST_SSR_HEAD__ !== void 0 ? __MOOST_SSR_HEAD__ : DEFAULT_SSR_HEAD);
 	const prefixes = normalizePrefixes(opts.prefix ?? __MOOST_PREFIX__);
 	const ssrForwarding = opts.ssrFetchForwarding ?? __MOOST_SSR_FORWARDING__ ?? true;
+	const variants = resolvePrecompressed(__MOOST_PRECOMPRESS__, opts.precompressed);
+	const cache = resolveCacheControl(__MOOST_CACHE_CONTROL__, opts.cacheControl);
 	const defaultPort = opts.port || Number(process.env.PORT) || 3e3;
 	const defaultHost = opts.host ?? process.env.HOST;
 	const template = await fs.readFile(path.resolve(clientDir, "index.html"), "utf8");
@@ -198,42 +345,36 @@ async function createSSRServer(options) {
 	}
 	MoostHttp.prototype.listen = origListen;
 	if (enableLocalFetch && moostHttpRef.instance) enableLocalFetch(moostHttpRef.instance);
-	const sirv = (await import("sirv")).default;
-	const serve = sirv(path.resolve(clientDir), { extensions: [] });
-	const serveStatic = (req, res) => {
-		const url = req.url || "/";
-		serve(req, res, async () => {
-			if (req.method !== "GET") {
-				res.statusCode = 404;
-				res.end();
-				return;
-			}
-			try {
-				if (render) {
-					const result = await renderSSRPage({
-						render,
-						url,
-						req,
-						res,
-						http: ssrForwarding ? moostHttpRef.instance : null
-					});
-					sendSSRResponse(res, template, {
-						ssrOutlet,
-						ssrState,
-						ssrHead
-					}, result);
-				} else {
-					res.statusCode = 200;
-					res.setHeader("Content-Type", "text/html");
-					res.end(template);
-				}
-			} catch (error) {
-				console.error(error);
-				res.statusCode = 500;
-				res.end(error.message);
-			}
-		});
+	const spaShell = render ? { html: template } : await loadSpaShell(clientDir, template, variants);
+	/** HTML page fallback: SSR render or the SPA shell. */ const servePage = async (req, res) => {
+		if (req.method !== "GET") {
+			res.statusCode = 404;
+			res.end();
+			return;
+		}
+		try {
+			if (render) {
+				const result = await renderSSRPage({
+					render,
+					url: req.url || "/",
+					req,
+					res,
+					http: ssrForwarding ? moostHttpRef.instance : null
+				});
+				if (cache?.html) presetHeader(res, "Cache-Control", cache.html);
+				sendSSRResponse(res, template, {
+					ssrOutlet,
+					ssrState,
+					ssrHead
+				}, result);
+			} else sendSpaShell(req, res, spaShell, cache);
+		} catch (error) {
+			console.error(error);
+			res.statusCode = 500;
+			res.end(error.message);
+		}
 	};
+	const serveStatic = await createStaticHandler(path.resolve(clientDir), variants, cache, (req, res) => void servePage(req, res));
 	return {
 		use(mw) {
 			userMiddlewares.push(mw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moostjs/vite",
-  "version": "0.6.48",
+  "version": "0.6.50",
   "description": "Vite Dev plugin for moostjs",
   "keywords": [
     "composables",
@@ -58,8 +58,8 @@
   "peerDependencies": {
     "sirv": "^3.0.0",
     "vite": "^8.0.0",
-    "@moostjs/event-http": "^0.6.48",
-    "moost": "^0.6.48"
+    "@moostjs/event-http": "^0.6.50",
+    "moost": "^0.6.50"
   },
   "peerDependenciesMeta": {
     "sirv": {