@moostjs/vite 0.6.53 → 0.7.0

package/README.md

@@ -92,7 +92,7 @@ app.init()
 
 Requests matching Moost routes (e.g. `/api/hello/world`) are handled by Moost with the full pipeline (interceptors, DI, validation). Everything else (`/`, `/about`, static assets) falls through to Vite.
 
-The optional `prefix` option adds a fast-path check — requests not matching the prefix skip Moost entirely:
+The optional `prefix` option declares the API mount(s) (a string or a list) — requests outside every mount skip Moost entirely, and an unmatched route under a mount gets Moost's `404` JSON error instead of the frontend's `index.html` — a static file under the mount (e.g. `/.well-known/security.txt`) is still served for `GET`/`HEAD` — and `prefixFallthrough: true` lets unmatched routes fall through instead:
 
 ```ts
 moostVite({
@@ -102,7 +102,7 @@ moostVite({
 })
 ```
 
-Note that the production server generated by `vite build` defaults the prefix to `'/api'` when the option is omitted — set `prefix` explicitly so dev (where all requests pass through Moost without it) and prod route the same way.
+Without `prefix`, every request enters Moost first and unmatched routes fall through to the frontend — in dev and in the generated production server alike.
 
 ## SSR Mode
 
@@ -272,7 +272,8 @@ The plugin injects a `__VITE_ID` decorator on `@Injectable` and `@Controller` cl
 | `onEject`          | `function`                                       | —                      | Hook to control DI instance ejection during HMR                                                                                                                                                                                                                                                                                                             |
 | `ssrFetch`         | `boolean`                                        | `true`                 | Enable local fetch interception for SSR                                                                                                                                                                                                                                                                                                                     |
 | `middleware`       | `boolean`                                        | `false`                | Run Moost as Connect middleware (Vite serves frontend)                                                                                                                                                                                                                                                                                                      |
-| `prefix`           | `string`                                         | `'/api'` (prod server) | URL prefix filter for middleware mode (e.g. `'/api'`); the production server defaults to `'/api'` when omitted                                                                                                                                                                                                                                              |
+| `prefix`           | `string \| string[]`                             | —                      | API mount(s) for middleware mode: requests outside skip Moost, unmatched routes inside get Moost's `404`                                                                                                                                                                                                                                                    |
+| `prefixFallthrough` | `boolean`                                        | `false`                | Let unmatched routes under `prefix` fall through to the frontend instead of Moost's `404`                                                                                                                                                                                                                                                                   |
 | `ssrEntry`         | `string`                                         | —                      | Vue/React SSR entry module (e.g. `'/src/entry-server.ts'`)                                                                                                                                                                                                                                                                                                  |
 | `ssrOutlet`        | `string`                                         | `'<!--ssr-outlet-->'`  | HTML placeholder for SSR-rendered content                                                                                                                                                                                                                                                                                                                   |
 | `ssrState`         | `string`                                         | `'<!--ssr-state-->'`   | HTML placeholder for SSR state transfer script                                                                                                                                                                                                                                                                                                              |

package/dist/index.cjs

@@ -816,6 +816,45 @@ const DEFAULT_PRECOMPRESS_INCLUDE = /\.(?:m?js|cjs|css|html?|svg|json|webmanifes
 		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 no-match handler of an API mount (a `prefix` without `prefixFallthrough`): a GET/HEAD
+* that names a static file is served (`tryStatic`, with `notFound` for a miss); anything else
+* gets Moost's own 404 — never the SPA shell or an SSR page.
+*/ function apiMountNoMatch(tryStatic, notFound) {
+	return (req, res) => {
+		if (req.method === "GET" || req.method === "HEAD") tryStatic(req, res, notFound);
+		else notFound(req, res);
+	};
+}
+/** Resolved public-dir roots (`publicDir` is fixed per dev server). */ const publicRoots = /* @__PURE__ */ new Map();
+/**
+* Whether `url` names a file inside `publicDir` (Vite's `public/`), for the dev server: a GET
+* under an API mount that no route matched is served from there before Moost's 404.
+*/ function isPublicFile(publicDir, url) {
+	if (!publicDir) return false;
+	let root = publicRoots.get(publicDir);
+	if (!root) {
+		root = (0, node_path.resolve)(publicDir);
+		publicRoots.set(publicDir, root);
+	}
+	const file = (0, node_path.resolve)(root, `.${requestPathname(url)}`);
+	if (file !== root && !file.startsWith(root + node_path.sep)) return false;
+	try {
+		return (0, node_fs.statSync)(file, { throwIfNoEntry: false })?.isFile() ?? false;
+	} catch {
+		return false;
+	}
+}
 
 //#endregion
 //#region packages/vite/src/moost-vite.ts
@@ -923,10 +962,10 @@ function moostVite(options) {
 				if (bootingGeneration !== bootGeneration) logger.error(`⚠️  A stale Moost boot captured the HTTP middleware (boot generation ${bootingGeneration}, latest ${bootGeneration}) — an HMR reload race; a follow-up reload will replace it.`);
 				httpCaptured = true;
 				moostHttpRef.current = this;
-				if (options.middleware) moostMiddleware = this.getServerCb((req) => {
-					pendingNextMap.get(req)?.();
-				});
-				else moostMiddleware = this.getServerCb();
+				if (options.middleware) {
+					const toVite = (req) => pendingNextMap.get(req)?.();
+					moostMiddleware = this.getServerCb(prefixes && !options.prefixFallthrough ? apiMountNoMatch((req, res, miss) => isPublicFile(resolvedConfig?.publicDir, req.url || "/") ? toVite(req) : miss(req, res), this.getServerCb()) : toVite);
+				} else moostMiddleware = this.getServerCb();
 				if (options.ssrFetch !== false && moduleExports?.enableLocalFetch) {
 					if (localFetchTeardown) localFetchTeardown();
 					localFetchTeardown = moduleExports.enableLocalFetch(this);
@@ -1046,6 +1085,7 @@ function moostVite(options) {
 					"process.env.MOOST_DEFERRED_ENV": "\"production\"",
 					__MOOST_ENTRY__: JSON.stringify(`./${entryKey}.js`),
 					__MOOST_PREFIX__: JSON.stringify(prefixes ?? null),
+					__MOOST_PREFIX_FALLTHROUGH__: JSON.stringify(options.prefixFallthrough === true),
 					__MOOST_SSR_FORWARDING__: JSON.stringify(ssrForwarding),
 					__MOOST_SSR_ENTRY__: "undefined",
 					__MOOST_SSR_OUTLET__: JSON.stringify(ssrOutlet),
@@ -1155,6 +1195,7 @@ function moostVite(options) {
 				ssrEntry: options.ssrEntry,
 				serverEntry: options.serverEntry,
 				prefix: prefixes,
+				prefixFallthrough: options.prefixFallthrough,
 				ssrOutlet: options.ssrOutlet,
 				ssrState: options.ssrState,
 				ssrHead: options.ssrHead,

package/dist/index.d.ts

@@ -146,7 +146,8 @@ interface TMoostViteDevOptions {
      * When enabled, Moost runs first and unmatched requests fall through to
      * Vite's default handler (static assets, Vue/React pages, HMR client).
      * With `prefix` configured, requests outside the mount(s) skip the Moost
-     * router entirely (fast path).
+     * router entirely (fast path), and unmatched routes inside a mount get
+     * Moost's 404 (see `prefix`).
      *
      * Use this for fullstack apps where Vite serves the frontend (Vue, React, etc.)
      * and Moost handles API routes.
@@ -158,13 +159,24 @@ interface TMoostViteDevOptions {
      * URL mount(s) for Moost routes in middleware mode — a single prefix or a
      * list of prefixes. Requests outside every mount skip the Moost router and
      * go straight to the frontend handler (an optimization/guard, in both dev
-     * and the generated prod server). When omitted, every request enters Moost
+     * and the generated prod server). A prefix is an API mount: an unmatched
+     * route under it gets Moost's own 404 (JSON) in dev and production instead
+     * of the SPA shell or an SSR page — set `prefixFallthrough: true` to let it
+     * fall through to the frontend. When omitted, every request enters Moost
      * first and unmatched routes fall through to the frontend.
      * Ignored when `middleware` is `false`.
      *
      * Example: `'/api'` or `['/api', '/.well-known']`
      */
     prefix?: string | string[];
+    /**
+     * Let unmatched routes under `prefix` fall through to the frontend (static
+     * files, SPA shell, SSR page) instead of answering Moost's 404.
+     * Applies in dev and is baked into the generated production server.
+     *
+     * Default: `false`.
+     */
+    prefixFallthrough?: boolean;
     /**
      * Vue/React SSR entry module path. Used by the SSR server helper
      * (`@moostjs/vite/server`) for server-side rendering.

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { createServerModuleRunner } from "vite";
 import MagicString from "magic-string";
@@ -787,6 +787,45 @@ const DEFAULT_PRECOMPRESS_INCLUDE = /\.(?:m?js|cjs|css|html?|svg|json|webmanifes
 		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 no-match handler of an API mount (a `prefix` without `prefixFallthrough`): a GET/HEAD
+* that names a static file is served (`tryStatic`, with `notFound` for a miss); anything else
+* gets Moost's own 404 — never the SPA shell or an SSR page.
+*/ function apiMountNoMatch(tryStatic, notFound) {
+	return (req, res) => {
+		if (req.method === "GET" || req.method === "HEAD") tryStatic(req, res, notFound);
+		else notFound(req, res);
+	};
+}
+/** Resolved public-dir roots (`publicDir` is fixed per dev server). */ const publicRoots = /* @__PURE__ */ new Map();
+/**
+* Whether `url` names a file inside `publicDir` (Vite's `public/`), for the dev server: a GET
+* under an API mount that no route matched is served from there before Moost's 404.
+*/ function isPublicFile(publicDir, url) {
+	if (!publicDir) return false;
+	let root = publicRoots.get(publicDir);
+	if (!root) {
+		root = resolve(publicDir);
+		publicRoots.set(publicDir, root);
+	}
+	const file = resolve(root, `.${requestPathname(url)}`);
+	if (file !== root && !file.startsWith(root + sep)) return false;
+	try {
+		return statSync(file, { throwIfNoEntry: false })?.isFile() ?? false;
+	} catch {
+		return false;
+	}
+}
 
 //#endregion
 //#region packages/vite/src/moost-vite.ts
@@ -892,10 +931,10 @@ function moostVite(options) {
 				if (bootingGeneration !== bootGeneration) logger.error(`⚠️  A stale Moost boot captured the HTTP middleware (boot generation ${bootingGeneration}, latest ${bootGeneration}) — an HMR reload race; a follow-up reload will replace it.`);
 				httpCaptured = true;
 				moostHttpRef.current = this;
-				if (options.middleware) moostMiddleware = this.getServerCb((req) => {
-					pendingNextMap.get(req)?.();
-				});
-				else moostMiddleware = this.getServerCb();
+				if (options.middleware) {
+					const toVite = (req) => pendingNextMap.get(req)?.();
+					moostMiddleware = this.getServerCb(prefixes && !options.prefixFallthrough ? apiMountNoMatch((req, res, miss) => isPublicFile(resolvedConfig?.publicDir, req.url || "/") ? toVite(req) : miss(req, res), this.getServerCb()) : toVite);
+				} else moostMiddleware = this.getServerCb();
 				if (options.ssrFetch !== false && moduleExports?.enableLocalFetch) {
 					if (localFetchTeardown) localFetchTeardown();
 					localFetchTeardown = moduleExports.enableLocalFetch(this);
@@ -1015,6 +1054,7 @@ function moostVite(options) {
 					"process.env.MOOST_DEFERRED_ENV": "\"production\"",
 					__MOOST_ENTRY__: JSON.stringify(`./${entryKey}.js`),
 					__MOOST_PREFIX__: JSON.stringify(prefixes ?? null),
+					__MOOST_PREFIX_FALLTHROUGH__: JSON.stringify(options.prefixFallthrough === true),
 					__MOOST_SSR_FORWARDING__: JSON.stringify(ssrForwarding),
 					__MOOST_SSR_ENTRY__: "undefined",
 					__MOOST_SSR_OUTLET__: JSON.stringify(ssrOutlet),
@@ -1124,6 +1164,7 @@ function moostVite(options) {
 				ssrEntry: options.ssrEntry,
 				serverEntry: options.serverEntry,
 				prefix: prefixes,
+				prefixFallthrough: options.prefixFallthrough,
 				ssrOutlet: options.ssrOutlet,
 				ssrState: options.ssrState,
 				ssrHead: options.ssrHead,

package/dist/prod-server.cjs

@@ -47,6 +47,16 @@ const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
 	}
 }
 /**
+* The no-match handler of an API mount (a `prefix` without `prefixFallthrough`): a GET/HEAD
+* that names a static file is served (`tryStatic`, with `notFound` for a miss); anything else
+* gets Moost's own 404 — never the SPA shell or an SSR page.
+*/ function apiMountNoMatch(tryStatic, notFound) {
+	return (req, res) => {
+		if (req.method === "GET" || req.method === "HEAD") tryStatic(req, res, notFound);
+		else notFound(req, res);
+	};
+}
+/**
 * 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).
@@ -111,7 +121,7 @@ const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
 /**
 * 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).
+* go to `fallback`, by default `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;
@@ -126,10 +136,10 @@ const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
 			if (vary) res.setHeader("Vary", vary);
 		}
 	});
-	return (req, res) => {
+	return (req, res, fallback = servePage) => {
 		const pathname = requestPathname(req.url || "/");
 		if (isIndexTemplatePath(pathname)) {
-			servePage(req, res);
+			fallback(req, res);
 			return;
 		}
 		const restore = [];
@@ -141,7 +151,7 @@ const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
 		}
 		serve(req, res, () => {
 			for (const undo of restore) undo();
-			servePage(req, res);
+			fallback(req, res);
 		});
 	};
 }
@@ -304,6 +314,7 @@ async function createSSRServer(options) {
 	const ssrState = opts.ssrState || (__MOOST_SSR_STATE__ !== void 0 ? __MOOST_SSR_STATE__ : DEFAULT_SSR_STATE);
 	const ssrHead = opts.ssrHead || (__MOOST_SSR_HEAD__ !== void 0 ? __MOOST_SSR_HEAD__ : DEFAULT_SSR_HEAD);
 	const prefixes = normalizePrefixes(opts.prefix ?? __MOOST_PREFIX__);
+	const prefixFallthrough = opts.prefixFallthrough ?? __MOOST_PREFIX_FALLTHROUGH__ ?? false;
 	const ssrForwarding = opts.ssrFetchForwarding ?? __MOOST_SSR_FORWARDING__ ?? true;
 	const variants = resolvePrecompressed(__MOOST_PRECOMPRESS__, opts.precompressed);
 	const cache = resolveCacheControl(__MOOST_CACHE_CONTROL__, opts.cacheControl);
@@ -321,7 +332,7 @@ async function createSSRServer(options) {
 	let captured = false;
 	const origListen = MoostHttp.prototype.listen;
 	MoostHttp.prototype.listen = function(...args) {
-		moostHandler = this.getServerCb((req, res) => serveStatic(req, res));
+		moostHandler = this.getServerCb(prefixes && !prefixFallthrough ? apiMountNoMatch((req, res, miss) => serveStatic(req, res, miss), this.getServerCb()) : (req, res) => serveStatic(req, res));
 		moostHttpRef.instance = this;
 		captured = true;
 		setTimeout(() => args.filter((a) => typeof a === "function").forEach((a) => a()), 1);

package/dist/prod-server.d.ts

@@ -85,10 +85,18 @@ interface TSSRServerOptions {
     /**
      * Override: URL mount(s) for Moost routes (e.g., '/api' or ['/api', '/.well-known']).
      * Requests outside every mount skip the Moost router (optimization/guard).
+     * A prefix is an API mount: an unmatched route under it gets Moost's own
+     * 404 (JSON), never the SPA shell or an SSR page (see `prefixFallthrough`).
      * When omitted (and not baked by the plugin), every request enters Moost first
      * and unmatched routes fall through to static/SSR — same as dev.
      */
     prefix?: string | string[];
+    /**
+     * Override: let unmatched routes under `prefix` fall through to static files
+     * and the SPA/SSR page instead of answering Moost's 404.
+     * Default: baked from the plugin's `prefixFallthrough` option (`false`).
+     */
+    prefixFallthrough?: boolean;
     /** Override: port number (default: process.env.PORT || 3000) */
     port?: number;
     /** Override: bind address, e.g. '127.0.0.1' (default: process.env.HOST, else all interfaces) */

package/dist/prod-server.mjs

@@ -1,7 +1,7 @@
 import { once } from "node:events";
+import "node:fs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import "node:fs";
 import "node:module";
 import { createLogger } from "moost";
 
@@ -48,6 +48,16 @@ const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
 	}
 }
 /**
+* The no-match handler of an API mount (a `prefix` without `prefixFallthrough`): a GET/HEAD
+* that names a static file is served (`tryStatic`, with `notFound` for a miss); anything else
+* gets Moost's own 404 — never the SPA shell or an SSR page.
+*/ function apiMountNoMatch(tryStatic, notFound) {
+	return (req, res) => {
+		if (req.method === "GET" || req.method === "HEAD") tryStatic(req, res, notFound);
+		else notFound(req, res);
+	};
+}
+/**
 * 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).
@@ -112,7 +122,7 @@ const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
 /**
 * 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).
+* go to `fallback`, by default `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;
@@ -127,10 +137,10 @@ const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
 			if (vary) res.setHeader("Vary", vary);
 		}
 	});
-	return (req, res) => {
+	return (req, res, fallback = servePage) => {
 		const pathname = requestPathname(req.url || "/");
 		if (isIndexTemplatePath(pathname)) {
-			servePage(req, res);
+			fallback(req, res);
 			return;
 		}
 		const restore = [];
@@ -142,7 +152,7 @@ const DEFAULT_REVALIDATE_CACHE_CONTROL = "no-cache";
 		}
 		serve(req, res, () => {
 			for (const undo of restore) undo();
-			servePage(req, res);
+			fallback(req, res);
 		});
 	};
 }
@@ -305,6 +315,7 @@ async function createSSRServer(options) {
 	const ssrState = opts.ssrState || (__MOOST_SSR_STATE__ !== void 0 ? __MOOST_SSR_STATE__ : DEFAULT_SSR_STATE);
 	const ssrHead = opts.ssrHead || (__MOOST_SSR_HEAD__ !== void 0 ? __MOOST_SSR_HEAD__ : DEFAULT_SSR_HEAD);
 	const prefixes = normalizePrefixes(opts.prefix ?? __MOOST_PREFIX__);
+	const prefixFallthrough = opts.prefixFallthrough ?? __MOOST_PREFIX_FALLTHROUGH__ ?? false;
 	const ssrForwarding = opts.ssrFetchForwarding ?? __MOOST_SSR_FORWARDING__ ?? true;
 	const variants = resolvePrecompressed(__MOOST_PRECOMPRESS__, opts.precompressed);
 	const cache = resolveCacheControl(__MOOST_CACHE_CONTROL__, opts.cacheControl);
@@ -322,7 +333,7 @@ async function createSSRServer(options) {
 	let captured = false;
 	const origListen = MoostHttp.prototype.listen;
 	MoostHttp.prototype.listen = function(...args) {
-		moostHandler = this.getServerCb((req, res) => serveStatic(req, res));
+		moostHandler = this.getServerCb(prefixes && !prefixFallthrough ? apiMountNoMatch((req, res, miss) => serveStatic(req, res, miss), this.getServerCb()) : (req, res) => serveStatic(req, res));
 		moostHttpRef.instance = this;
 		captured = true;
 		setTimeout(() => args.filter((a) => typeof a === "function").forEach((a) => a()), 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moostjs/vite",
-  "version": "0.6.53",
+  "version": "0.7.0",
   "description": "Vite Dev plugin for moostjs",
   "keywords": [
     "composables",
@@ -50,21 +50,16 @@
     ]
   },
   "dependencies": {
-    "magic-string": "^0.30.21"
+    "magic-string": "^0.30.21",
+    "sirv": "^3.0.2"
   },
   "devDependencies": {
     "vitest": "3.2.7"
   },
   "peerDependencies": {
-    "sirv": "^3.0.0",
     "vite": "^8.0.0",
-    "@moostjs/event-http": "^0.6.53",
-    "moost": "^0.6.53"
-  },
-  "peerDependenciesMeta": {
-    "sirv": {
-      "optional": true
-    }
+    "@moostjs/event-http": "^0.7.0",
+    "moost": "^0.7.0"
   },
   "scripts": {
     "pub": "pnpm publish --access public",