@troyio/vite-file-router 0.4.1 → 0.6.0

package/dist/index.js

@@ -11,7 +11,9 @@ var DEFAULT_CONVENTIONS = {
 	notFound: "not-found",
 	error: "error",
 	loader: "loader",
-	action: "action"
+	action: "action",
+	middleware: "middleware",
+	hydrateFallback: "hydrate-fallback"
 };
 function getRouteSegment(name) {
 	if (name.startsWith("[...") && name.endsWith("]")) return "*";
@@ -68,7 +70,7 @@ function scan(directory, conventions = DEFAULT_CONVENTIONS) {
 		const [, basename, extension] = match;
 		const kind = Object.keys(conventions).find((candidate) => conventions[candidate] === basename);
 		if (!kind) continue;
-		const isDataModule = kind === "loader" || kind === "action";
+		const isDataModule = kind === "loader" || kind === "action" || kind === "middleware";
 		if (!(isDataModule ? ["js", "ts"] : ["jsx", "tsx"]).includes(extension)) continue;
 		const preferredExtension = isDataModule ? "ts" : "tsx";
 		if (!node[kind] || extension === preferredExtension) node[kind] = file;
@@ -177,8 +179,9 @@ function generatePreload(files, projectRoot, children = []) {
 /**
 * Dev-only client for the DevTools Routes panel. It reports the tab's current
 * URL and every loader, action, and `shouldRevalidate` call over Vite's HMR
-* channel. Handler results pass through unchanged; only a short text preview
-* of returned data is sent. Production builds never include this code.
+* channel. Handler results pass through unchanged; the panel gets a capped
+* copy of params, submitted form fields, returned data, response details, and
+* errors. Production builds never include this code.
 */
 var DEVTOOLS_CLIENT = `const devtoolsHot =
   typeof window === "undefined" ? undefined : import.meta.hot;
@@ -190,33 +193,149 @@ function sendToDevtools(event, payload) {
   } catch {}
 }
 
+const DEVTOOLS_DATA_LIMIT = 8000;
+const DEVTOOLS_TEXT_LIMIT = 4000;
+
+function clipText(text, limit) {
+  return text.length > limit ? text.slice(0, limit) + "…" : text;
+}
+
+// Serializes loader and action results for the panel. Circular references,
+// Maps, Sets, bigints, and functions don't break serialization.
+function serializeRouteData(value, limit = DEVTOOLS_DATA_LIMIT) {
+  const stack = [];
+  let text;
+  try {
+    text = JSON.stringify(value, function (_key, item) {
+      if (stack.length > 0) {
+        const position = stack.indexOf(this);
+        if (position === -1) stack.push(this);
+        else stack.splice(position + 1);
+        if (item && typeof item === "object" && stack.includes(item)) {
+          return "[Circular]";
+        }
+      } else {
+        stack.push(item);
+      }
+      if (typeof item === "bigint") return item.toString() + "n";
+      if (typeof item === "function") {
+        return "[Function " + (item.name || "anonymous") + "]";
+      }
+      if (typeof item === "symbol") return item.toString();
+      if (item instanceof Map) {
+        return Object.fromEntries(
+          [...item].map(([key, entry]) => [String(key), entry]),
+        );
+      }
+      if (item instanceof Set) return [...item];
+      return item;
+    });
+  } catch {}
+  if (text === undefined) text = String(value);
+  return text.length > limit
+    ? { data: text.slice(0, limit), dataTruncated: true }
+    : { data: text };
+}
+
 function previewRouteData(value) {
+  return clipText(serializeRouteData(value, 601).data, 600);
+}
+
+function routeParams(params) {
+  if (!params || typeof params !== "object") return undefined;
+  const entries = Object.entries(params).filter(
+    ([, value]) => typeof value === "string",
+  );
+  return entries.length ? Object.fromEntries(entries) : undefined;
+}
+
+async function describeRequestBody(request) {
+  const type = request.headers.get("Content-Type") || "";
   try {
-    const text = JSON.stringify(value, (_key, item) =>
-      typeof item === "bigint" ? String(item) : item,
-    );
-    if (text === undefined) return String(value);
-    return text.length > 600 ? text.slice(0, 600) + "…" : text;
+    if (
+      type.includes("multipart/form-data") ||
+      type.includes("application/x-www-form-urlencoded")
+    ) {
+      const form = await request.formData();
+      return {
+        kind: "form",
+        entries: [...form].slice(0, 50).map(([name, value]) => [
+          name,
+          typeof value === "string"
+            ? clipText(value, 500)
+            : "File " + value.name + " (" + value.size + " bytes)",
+        ]),
+      };
+    }
+    const text = await request.text();
+    return text
+      ? { kind: "text", contentType: type, text: clipText(text, DEVTOOLS_TEXT_LIMIT) }
+      : undefined;
   } catch {
-    return String(value);
+    return undefined;
   }
 }
 
-function describeRouteResult(value, thrown) {
-  if (value instanceof Response) {
-    const location = value.headers.get("Location");
-    if (location && value.status >= 300 && value.status < 400) {
-      return { outcome: "redirect", status: value.status, location };
-    }
-    return { outcome: thrown ? "error" : "response", status: value.status };
+function headerEntries(headers) {
+  try {
+    return [...new Headers(headers)].slice(0, 40);
+  } catch {
+    return undefined;
+  }
+}
+
+// Clones a Response synchronously, before React Router reads its body.
+function describeResponse(value, thrown) {
+  const location = value.headers.get("Location");
+  const base = { status: value.status, headers: headerEntries(value.headers) };
+  if (location && value.status >= 300 && value.status < 400) {
+    return { ...base, outcome: "redirect", location };
   }
+  const outcome = thrown ? "error" : "response";
+  if (value.bodyUsed || !value.body) return { ...base, outcome };
+  const copy = value.clone();
+  return copy
+    .text()
+    .then((text) => ({
+      ...base,
+      outcome,
+      ...(text ? { responseBody: clipText(text, DEVTOOLS_TEXT_LIMIT) } : {}),
+    }))
+    .catch(() => ({ ...base, outcome }));
+}
+
+function describeRouteResult(value, thrown) {
+  if (value instanceof Response) return describeResponse(value, thrown);
   if (thrown) {
+    if (value instanceof Error) {
+      return {
+        outcome: "error",
+        errorName: value.name,
+        message: value.message,
+        stack: value.stack ? clipText(value.stack, DEVTOOLS_TEXT_LIMIT) : undefined,
+      };
+    }
     return {
       outcome: "error",
-      message: value instanceof Error ? value.message : previewRouteData(value),
+      message: previewRouteData(value),
+      ...serializeRouteData(value),
     };
   }
-  return { outcome: "data", preview: previewRouteData(value) };
+  // React Router's data() helper wraps data with a status and headers.
+  if (value && value.type === "DataWithResponseInit" && "data" in value) {
+    return {
+      outcome: "data",
+      status: value.init?.status,
+      headers: value.init?.headers ? headerEntries(value.init.headers) : undefined,
+      preview: previewRouteData(value.data),
+      ...serializeRouteData(value.data),
+    };
+  }
+  return {
+    outcome: "data",
+    preview: previewRouteData(value),
+    ...serializeRouteData(value),
+  };
 }
 
 function instrumentRouteData(type, routeId, handler) {
@@ -225,16 +344,30 @@ function instrumentRouteData(type, routeId, handler) {
     const startedAt = Date.now();
     const started = performance.now();
     const request = args?.request;
-    const report = (result, thrown) =>
-      sendToDevtools("vite-file-router:data", {
-        type,
-        routeId,
-        url: request?.url,
-        method: request?.method,
-        startedAt,
-        duration: performance.now() - started,
-        ...describeRouteResult(result, thrown),
-      });
+    // Read the submitted body from a copy, so the handler can still read it.
+    const body =
+      request && request.body && request.method !== "GET" && request.method !== "HEAD"
+        ? describeRequestBody(request.clone())
+        : undefined;
+    const report = (result, thrown) => {
+      const duration = performance.now() - started;
+      const described = describeRouteResult(result, thrown);
+      Promise.all([described, body])
+        .then(([details, requestBody]) =>
+          sendToDevtools("vite-file-router:data", {
+            type,
+            routeId,
+            url: request?.url,
+            method: request?.method,
+            params: routeParams(args?.params),
+            body: requestBody,
+            startedAt,
+            duration,
+            ...details,
+          }),
+        )
+        .catch(() => {});
+    };
     try {
       const result = await handler(args);
       report(result, false);
@@ -246,6 +379,55 @@ function instrumentRouteData(type, routeId, handler) {
   };
 }
 
+// Reports the middleware's own time, not counting the handlers next() runs.
+function instrumentMiddleware(routeId, middleware) {
+  if (!devtoolsHot) return middleware;
+  return async (args, next) => {
+    const startedAt = Date.now();
+    const started = performance.now();
+    let downstream = 0;
+    let calledNext = false;
+    const timedNext = async () => {
+      calledNext = true;
+      const nextStarted = performance.now();
+      try {
+        return await next();
+      } finally {
+        downstream += performance.now() - nextStarted;
+      }
+    };
+    const report = (details) => {
+      const duration = performance.now() - started - downstream;
+      Promise.resolve(details)
+        .then((resolved) =>
+          sendToDevtools("vite-file-router:data", {
+            type: "middleware",
+            routeId,
+            url: args?.request?.url,
+            method: args?.request?.method,
+            params: routeParams(args?.params),
+            startedAt,
+            duration,
+            ...resolved,
+          }),
+        )
+        .catch(() => {});
+    };
+    try {
+      const result = await middleware(args, timedNext);
+      report(
+        result instanceof Response && !calledNext
+          ? describeRouteResult(result, false)
+          : { outcome: "next" },
+      );
+      return result;
+    } catch (error) {
+      report(describeRouteResult(error, true));
+      throw error;
+    }
+  };
+}
+
 function instrumentRevalidate(routeId, shouldRevalidate) {
   if (!devtoolsHot) return shouldRevalidate;
   return (args) => {
@@ -254,6 +436,10 @@ function instrumentRevalidate(routeId, shouldRevalidate) {
       type: "revalidate",
       routeId,
       url: args?.nextUrl?.href,
+      currentUrl: args?.currentUrl?.href,
+      params: routeParams(args?.nextParams),
+      formMethod: args?.formMethod,
+      actionStatus: args?.actionStatus,
       startedAt: Date.now(),
       decision,
       defaultShouldRevalidate: args?.defaultShouldRevalidate,
@@ -290,6 +476,30 @@ if (devtoolsHot) {
   for (const event of ["vite-file-router:navigate", "popstate", "hashchange"]) {
     window.addEventListener(event, reportLocation);
   }
+  // The panel's "Open in app" action. React Router's browser router follows
+  // popstate events, so pushing the URL and announcing it navigates without a
+  // reload. The state matches React Router's so Back and Forward keep working.
+  devtoolsHot.on("vite-file-router:navigate", (payload) => {
+    const url = payload?.url;
+    if (typeof url !== "string" || !url.startsWith("/") || url.startsWith("//")) {
+      return;
+    }
+    if (window.location.hash.startsWith("#/")) {
+      window.location.hash = url;
+      return;
+    }
+    const index = window.history.state?.idx;
+    window.history.pushState(
+      {
+        usr: null,
+        key: Math.random().toString(36).slice(2, 10),
+        idx: typeof index === "number" ? index + 1 : 0,
+      },
+      "",
+      url,
+    );
+    window.dispatchEvent(new PopStateEvent("popstate", { state: window.history.state }));
+  });
   // Report again after the dev server restarts and the socket reconnects.
   devtoolsHot.on("vite:ws:connect", () => {
     reportedUrl = undefined;
@@ -311,6 +521,17 @@ function generateNode(node, root, context, inheritedBoundary) {
 		route.ErrorBoundary = `createErrorBoundary(${generateLazyComponent(node.error, context.projectRoot)})`;
 	}
 	if (node.action) route.action = generateDataHandler(node.action, context.projectRoot, getInstrumentId(node, context));
+	if (node.middleware) {
+		context.hasMiddleware = true;
+		const load = `lazyMiddleware(() => import(${JSON.stringify(getImportPath(node.middleware, context.projectRoot))}))`;
+		const instrumentId = getInstrumentId(node, context);
+		route.middleware = `[${instrumentId ? `instrumentMiddleware(${JSON.stringify(instrumentId)}, ${load})` : load}]`;
+	}
+	if (node.hydrateFallback) {
+		const fallback = genSafeVariableName(`HydrateFallback${context.nextLoadingId++}`);
+		context.loadingImports.push(`import ${fallback} from ${JSON.stringify(getImportPath(node.hydrateFallback, context.projectRoot))};`);
+		route.HydrateFallback = fallback;
+	}
 	let loadingComponent;
 	if (node.loading) {
 		loadingComponent = genSafeVariableName(`Loading${context.nextLoadingId++}`);
@@ -358,7 +579,11 @@ function generateNode(node, root, context, inheritedBoundary) {
 	if (children.length) route.children = genArrayFromRaw(children);
 	return {
 		route: genObjectFromRaw(route),
-		preload: generatePreload([node.layout, node.loader], context.projectRoot, preloadChildren)
+		preload: generatePreload([
+			node.layout,
+			node.loader,
+			node.middleware
+		], context.projectRoot, preloadChildren)
 	};
 }
 function generate(node, root = false, projectRoot = process.cwd(), options = {}) {
@@ -372,6 +597,7 @@ function generate(node, root = false, projectRoot = process.cwd(), options = {})
 		hasBoundaries: false,
 		hasLayouts: false,
 		hasErrorBoundaries: false,
+		hasMiddleware: false,
 		devClient: Boolean(options.devClient)
 	};
 	const { route: routes, preload: preloads } = generateNode(node, root, context, false);
@@ -409,6 +635,31 @@ function generate(node, root = false, projectRoot = process.cwd(), options = {})
       createElement(Component),
     );
   };
+}`);
+	if (context.hasMiddleware) helpers.push(`/**
+ * Runs a middleware module's default or \`middleware\` export, which can be a
+ * function or an array of functions. Like React Router, it calls \`next()\`
+ * after a function that didn't call it.
+ */
+function lazyMiddleware(load) {
+  let pending;
+  return async (args, next) => {
+    pending ??= load();
+    const module = await pending;
+    const exported = module.middleware ?? module.default;
+    const list = (Array.isArray(exported) ? exported : [exported]).filter(
+      (item) => typeof item === "function",
+    );
+    const run = async (index) => {
+      if (index >= list.length) return next();
+      let downstream;
+      const callNext = () => (downstream ??= run(index + 1));
+      const result = await list[index](args, callNext);
+      const nextResult = await callNext();
+      return result === undefined ? nextResult : result;
+    };
+    return run(0);
+  };
 }`);
 	if (context.devClient) helpers.push(DEVTOOLS_CLIENT);
 	return {
@@ -474,6 +725,80 @@ function createRouteDeclarations(tree, projectRoot, declarationFile) {
 // src/devtools.ts
 var ROUTE_INSPECTOR_PATH = "/__vite-file-router/";
 var HEARTBEAT_INTERVAL = 25e3;
+var EXPORT_PATTERNS = (name) => [
+	new RegExp(`export\\s+(?:async\\s+)?function\\s*\\*?\\s*${name}\\b`),
+	new RegExp(`export\\s+(?:const|let|var)\\s+${name}\\b`),
+	new RegExp(`export\\s*\\{[^}]*\\b${name}\\b[^}]*\\}`),
+	/export\s*\*\s*from/
+];
+/** Whether module source code (probably) has a named export. */
+function hasNamedExport(source, name) {
+	return EXPORT_PATTERNS(name).some((pattern) => pattern.test(source));
+}
+var MISSING_EXPORT_MESSAGES = {
+	loader: `This loader file doesn't export a function named "loader", so the route loads no data.`,
+	action: `This action file doesn't export a function named "action", so the route fails when a form is submitted.`,
+	middleware: "This middleware file has no default or \"middleware\" export, so no middleware runs for the route."
+};
+var HANDLER_NAMES = {
+	loader: "a loader",
+	action: "an action",
+	middleware: "middleware"
+};
+function listHandlers(kinds) {
+	const names = kinds.map((kind) => HANDLER_NAMES[kind]);
+	return names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+}
+/**
+* Finds routes that are missing a file they likely need: an error file for a
+* loader, action, or middleware, a root not-found page, or the expected export
+* of a data module. `readSource` reads a project-relative file.
+*/
+function findRouteWarnings(manifest, readSource = () => void 0) {
+	const warnings = [];
+	if (!manifest.files.notFound) warnings.push({
+		kind: "no-not-found",
+		severity: manifest.files.error ? "info" : "warning",
+		key: "0",
+		fullPath: "/",
+		message: manifest.files.error ? "There's no root not-found page, so unknown URLs render the root error file with a 404 error." : "There's no root not-found page or error file, so unknown URLs show React Router's default error screen.",
+		files: manifest.files.error ? [manifest.files.error] : []
+	});
+	const visit = (node, key, hasError) => {
+		const covered = hasError || Boolean(node.files.error);
+		const handlers = [
+			"loader",
+			"action",
+			"middleware"
+		].filter((kind) => node.files[kind]);
+		if (handlers.length && !covered) warnings.push({
+			kind: "no-error-boundary",
+			severity: "warning",
+			key,
+			fullPath: node.fullPath,
+			message: `This route has ${listHandlers(handlers)} but no error file at or above it, so errors it throws show React Router's default error screen.`,
+			files: handlers.map((kind) => node.files[kind])
+		});
+		for (const kind of handlers) {
+			const file = node.files[kind];
+			const source = readSource(file);
+			if (source === void 0) continue;
+			if (!(hasNamedExport(source, kind) || kind === "middleware" && /export\s+default\b/.test(source))) warnings.push({
+				kind: "missing-export",
+				severity: "warning",
+				key,
+				fullPath: node.fullPath,
+				message: MISSING_EXPORT_MESSAGES[kind],
+				files: [file]
+			});
+		}
+		node.children.forEach((child, index) => {
+			visit(child, `${key}.${index}`, covered);
+		});
+	};
+	visit(manifest, "0", false);
+	return warnings;
+}
 /**
 * Mirrors the generated React Router tree: each manifest node becomes a
 * route with an index child for its page and a `*` child for its not-found
@@ -524,7 +849,9 @@ async function matchRouteManifest(manifest, url) {
 		...leaf.kind === "notFound" ? { notFound: leaf.node?.files.notFound } : {},
 		layouts: collect("layout"),
 		loaders: collect("loader"),
+		middleware: collect("middleware"),
 		...nearest("loading") ? { loading: nearest("loading") } : {},
+		...nearest("hydrateFallback") ? { hydrateFallback: nearest("hydrateFallback") } : {},
 		...nearest("error") ? { error: nearest("error") } : {}
 	};
 }
@@ -581,8 +908,19 @@ function createRouteEventStream(getState, getSnapshot = () => []) {
 /** HMR events the dev-only client in `virtual:routes` sends to the server. */
 var APP_LOCATION_EVENT = "vite-file-router:location";
 var APP_DATA_EVENT = "vite-file-router:data";
+/** Sent from the server to the app: navigate one tab to a URL. */
+var APP_NAVIGATE_EVENT = "vite-file-router:navigate";
+/**
+* Checks a URL the panel asks an app tab to open. Only same-origin paths are
+* allowed, so the panel can't send the app to another site.
+*/
+function isAppPath(url) {
+	return typeof url === "string" && url.length <= 2e3 && url.startsWith("/") && !url.startsWith("//") && !url.startsWith("/\\") && ![...url].some((character) => character.charCodeAt(0) < 32);
+}
 var MAX_ACTIVITY = 200;
 var MAX_TEXT = 600;
+var MAX_DATA = 8e3;
+var MAX_DETAIL = 4e3;
 function text(value, limit = MAX_TEXT) {
 	if (typeof value !== "string") return void 0;
 	return value.length > limit ? `${value.slice(0, limit)}…` : value;
@@ -590,6 +928,29 @@ function text(value, limit = MAX_TEXT) {
 function finite(value) {
 	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
+function pairs(value, max, limit) {
+	if (!Array.isArray(value)) return void 0;
+	return value.filter((entry) => Array.isArray(entry) && typeof entry[0] === "string" && typeof entry[1] === "string").slice(0, max).map(([name, item]) => [text(name, 200), text(item, limit)]);
+}
+function stringRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string").slice(0, 30).map(([name, item]) => [text(name, 100), text(item, 1e3)]);
+	return entries.length ? Object.fromEntries(entries) : void 0;
+}
+function requestBody(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const body = value;
+	if (body.kind === "form") return {
+		kind: "form",
+		entries: pairs(body.entries, 50, 500) ?? []
+	};
+	const bodyText = text(body.text, MAX_DETAIL);
+	if (body.kind === "text" && bodyText !== void 0) return {
+		kind: "text",
+		contentType: text(body.contentType, 200),
+		text: bodyText
+	};
+}
 /**
 * Validates an event from the browser. Anything a page sends over the HMR
 * channel is untrusted, so only known fields of the expected types are kept.
@@ -598,7 +959,7 @@ function sanitizeDataEvent(input, id) {
 	if (!input || typeof input !== "object") return void 0;
 	const event = input;
 	const type = event.type;
-	if (type !== "loader" && type !== "action" && type !== "revalidate") return;
+	if (type !== "loader" && type !== "action" && type !== "middleware" && type !== "revalidate") return;
 	const routeId = text(event.routeId, 400);
 	const tabId = text(event.tabId, 100);
 	if (!routeId || !tabId) return void 0;
@@ -612,13 +973,24 @@ function sanitizeDataEvent(input, id) {
 		method: text(event.method, 20),
 		startedAt: finite(event.startedAt) ?? Date.now(),
 		duration: finite(event.duration),
-		...outcome === "data" || outcome === "response" || outcome === "redirect" || outcome === "error" ? { outcome } : {},
+		...outcome === "data" || outcome === "response" || outcome === "redirect" || outcome === "error" || outcome === "next" ? { outcome } : {},
 		status: finite(event.status),
 		location: text(event.location, 2e3),
 		message: text(event.message),
 		preview: text(event.preview),
 		...typeof event.decision === "boolean" ? { decision: event.decision } : {},
-		...typeof event.defaultShouldRevalidate === "boolean" ? { defaultShouldRevalidate: event.defaultShouldRevalidate } : {}
+		...typeof event.defaultShouldRevalidate === "boolean" ? { defaultShouldRevalidate: event.defaultShouldRevalidate } : {},
+		params: stringRecord(event.params),
+		body: requestBody(event.body),
+		data: text(event.data, MAX_DATA),
+		...event.dataTruncated === true ? { dataTruncated: true } : {},
+		headers: pairs(event.headers, 40, 1e3),
+		responseBody: text(event.responseBody, MAX_DETAIL),
+		errorName: text(event.errorName, 200),
+		stack: text(event.stack, MAX_DETAIL),
+		currentUrl: text(event.currentUrl, 2e3),
+		formMethod: text(event.formMethod, 20),
+		actionStatus: finite(event.actionStatus)
 	};
 }
 /**
@@ -657,6 +1029,10 @@ function createAppTracker(options) {
 			});
 			changed();
 		},
+		/** The HMR client for an app tab, to send it events such as navigation. */
+		clientFor(tabId) {
+			for (const [client, tab] of tabs) if (tab.id === tabId) return client;
+		},
 		disconnect(client) {
 			latestReport.delete(client);
 			if (tabs.delete(client)) changed();
@@ -688,6 +1064,11 @@ var MANIFEST_MODULE_ID = "virtual:route-manifest";
 var MANIFEST_RESOLVED_ID = `\0${MANIFEST_MODULE_ID}`;
 var ROUTE_HELPERS_MODULE_ID = "virtual:route-helpers";
 var ROUTE_HELPERS_RESOLVED_ID = `\0${ROUTE_HELPERS_MODULE_ID}`;
+var WARNING_KINDS = [
+	"no-error-boundary",
+	"no-not-found",
+	"missing-export"
+];
 var DEFAULT_DTS = "src/route-types.d.ts";
 var TYPESCRIPT_CONFIG_FILES = ["tsconfig.json", "jsconfig.json"];
 function resolveDeclarationFile(dts, projectRoot) {
@@ -698,7 +1079,7 @@ function resolveDeclarationFile(dts, projectRoot) {
 function resolveOptions(input) {
 	const options = typeof input === "string" ? { directory: input } : input;
 	if (!options || typeof options !== "object" || Array.isArray(options)) throw new TypeError("routes() expects a directory string or options object.");
-	for (const key of Object.keys(options)) if (key !== "directory" && key !== "conventions" && key !== "dts") throw new TypeError(`Unknown routes() option "${key}".`);
+	for (const key of Object.keys(options)) if (key !== "directory" && key !== "conventions" && key !== "dts" && key !== "warnings") throw new TypeError(`Unknown routes() option "${key}".`);
 	const directory = options.directory ?? "src/pages";
 	if (typeof directory !== "string" || directory.trim() === "") throw new TypeError("routes() directory must be a non-empty path string.");
 	const conventions = { ...DEFAULT_CONVENTIONS };
@@ -715,21 +1096,80 @@ function resolveOptions(input) {
 	return {
 		directory,
 		conventions,
-		dts
+		dts,
+		warnings: resolveWarnings(options.warnings)
+	};
+}
+function resolveWarnings(input) {
+	const message = "routes() warnings must be \"warn\", \"error\", false, or { level, ignore }.";
+	if (input === void 0 || input === "warn") return {
+		level: "warn",
+		ignore: []
+	};
+	if (input === "error") return {
+		level: "error",
+		ignore: []
+	};
+	if (input === false) return false;
+	if (!input || typeof input !== "object" || Array.isArray(input)) throw new TypeError(message);
+	for (const key of Object.keys(input)) if (key !== "level" && key !== "ignore") throw new TypeError(message);
+	const level = input.level ?? "warn";
+	if (level !== "warn" && level !== "error") throw new TypeError(message);
+	const ignore = input.ignore ?? [];
+	if (!Array.isArray(ignore) || ignore.some((kind) => !WARNING_KINDS.includes(kind))) throw new TypeError(`routes() warnings.ignore must list warning kinds: ${WARNING_KINDS.join(", ")}.`);
+	return {
+		level,
+		ignore
 	};
 }
+/** Formats route warnings for the terminal, grouped by route. */
+function formatRouteWarnings(warnings) {
+	const byRoute = /* @__PURE__ */ new Map();
+	for (const warning of warnings) byRoute.set(warning.fullPath, [...byRoute.get(warning.fullPath) ?? [], warning]);
+	const lines = [`vite-file-router found ${warnings.length} route warning${warnings.length === 1 ? "" : "s"}:`];
+	for (const [fullPath, list] of byRoute) {
+		lines.push("", `  ${fullPath}`);
+		for (const warning of list) {
+			lines.push(`    - ${warning.message} [${warning.kind}]`);
+			for (const file of warning.files) lines.push(`      ${file}`);
+		}
+	}
+	lines.push("", "Ignore a kind with routes({ warnings: { ignore: [...] } }), or turn these off with routes({ warnings: false }).");
+	return lines.join("\n");
+}
 function routes(input = "src/pages") {
 	const options = resolveOptions(input);
 	let projectRoot = "";
 	let root = "";
 	let dev = false;
 	let declarationFile;
+	function readSource(file) {
+		try {
+			return fs.readFileSync(path.resolve(projectRoot, file), "utf8");
+		} catch {
+			return;
+		}
+	}
+	let reportedWarnings;
+	function reportBuildWarnings(context) {
+		if (dev || !options.warnings) return;
+		const { level, ignore } = options.warnings;
+		const warnings = findRouteWarnings(createRouteManifest(scan(root, options.conventions), projectRoot), readSource).filter((warning) => warning.severity === "warning" && !ignore.includes(warning.kind));
+		if (!warnings.length) return;
+		const message = formatRouteWarnings(warnings);
+		if (level === "error") context.error(message);
+		if (message === reportedWarnings) return;
+		reportedWarnings = message;
+		context.warn(message);
+	}
 	function getInspectorState() {
 		const tree = scan(root, options.conventions);
+		const manifest = createRouteManifest(tree, projectRoot);
 		return {
 			projectRoot,
 			directory: path.relative(projectRoot, root).split(path.sep).join("/"),
-			manifest: createRouteManifest(tree, projectRoot),
+			manifest,
+			warnings: findRouteWarnings(manifest, readSource),
 			conflicts: findPageRouteConflicts(tree).map(({ routePath, files }) => ({
 				routePath,
 				files: files.map((file) => path.relative(projectRoot, file).split(path.sep).join("/"))
@@ -742,6 +1182,44 @@ function routes(input = "src/pages") {
 		onActivity: (event) => routeEvents.broadcast("activity", event)
 	});
 	const routeEvents = createRouteEventStream(getInspectorState, () => [["apps", appTracker.tabs()], ["activity-snapshot", appTracker.activity()]]);
+	/**
+	* Every module the plugin generates, for the DevTools Generated code page.
+	* A module that fails to generate (for example on a route conflict)
+	* reports its error instead of failing the others.
+	*/
+	async function getGeneratedCode() {
+		const capture = async (module, create) => {
+			try {
+				return {
+					...module,
+					code: await create()
+				};
+			} catch (error) {
+				return {
+					...module,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		};
+		const typesFile = declarationFile ?? path.resolve(projectRoot, DEFAULT_DTS);
+		return Promise.all([
+			capture({
+				id: ROUTES_MODULE_ID,
+				variant: "dev"
+			}, () => execute(true)),
+			capture({
+				id: ROUTES_MODULE_ID,
+				variant: "build"
+			}, () => execute(false)),
+			capture({ id: MANIFEST_MODULE_ID }, executeManifest),
+			capture({ id: ROUTE_HELPERS_MODULE_ID }, executeRouteHelpers),
+			capture({
+				id: "route-types",
+				file: path.relative(projectRoot, typesFile).split(path.sep).join("/"),
+				written: Boolean(declarationFile)
+			}, () => createRouteDeclarations(scan(root, options.conventions), projectRoot, typesFile))
+		]);
+	}
 	function writeDeclarations() {
 		if (!declarationFile) return;
 		const content = createRouteDeclarations(scan(root, options.conventions), projectRoot, declarationFile);
@@ -758,12 +1236,13 @@ function routes(input = "src/pages") {
 			return leftSource.localeCompare(rightSource);
 		});
 	}
-	async function execute() {
+	/** `devClient` adds the DevTools client, which only the dev server serves. */
+	async function execute(devClient = dev) {
 		const tree = scan(root, options.conventions);
 		const conflicts = findPageRouteConflicts(tree);
 		if (conflicts.length) {
 			const error = new RouteConflictError(conflicts);
-			if (!dev) throw error;
+			if (!devClient) throw error;
 			const code = `
         import { createElement } from "react";
 
@@ -787,7 +1266,7 @@ function routes(input = "src/pages") {
       `;
 			return format(code, { parser: "typescript" });
 		}
-		const generated = generate(tree, true, projectRoot, { devClient: dev });
+		const generated = generate(tree, true, projectRoot, { devClient });
 		const sections = [
 			sortImports(generated.imports).join("\n"),
 			generated.helpers.join("\n"),
@@ -925,6 +1404,13 @@ function routes(input = "src/pages") {
 		},
 		buildStart() {
 			writeDeclarations();
+			reportBuildWarnings({
+				warn: (message) => typeof this?.warn === "function" ? this.warn(message) : console.warn(message),
+				error: (message) => {
+					if (typeof this?.error === "function") this.error(message);
+					throw new Error(message);
+				}
+			});
 		},
 		resolveId: (id) => {
 			if (id === ROUTES_MODULE_ID) return ROUTES_RESOLVED_ID;
@@ -946,6 +1432,43 @@ function routes(input = "src/pages") {
 				type: "iframe",
 				url: ROUTE_INSPECTOR_PATH
 			});
+			const fail = (res, status, message) => {
+				res.statusCode = status;
+				res.setHeader("Content-Type", "text/plain; charset=utf-8");
+				res.end(message);
+			};
+			const navigateApp = (req, res) => {
+				if (!req.headers["content-type"]?.startsWith("application/json")) {
+					fail(res, 415, "Expected a JSON body.");
+					return;
+				}
+				let body = "";
+				req.setEncoding?.("utf8");
+				req.on("data", (chunk) => {
+					body += chunk;
+					if (body.length > 8192) req.destroy();
+				});
+				req.on("end", () => {
+					let payload;
+					try {
+						payload = JSON.parse(body);
+					} catch {
+						fail(res, 400, "Invalid JSON.");
+						return;
+					}
+					if (!isAppPath(payload?.url)) {
+						fail(res, 400, "The \"url\" must be a path starting with \"/\".");
+						return;
+					}
+					const client = appTracker.clientFor(String(payload.tabId));
+					if (!client) {
+						fail(res, 404, "That app tab is no longer connected.");
+						return;
+					}
+					client.send(APP_NAVIGATE_EVENT, { url: payload.url });
+					sendJson(res, { sent: true });
+				});
+			};
 			const sendJson = (res, body) => {
 				res.statusCode = 200;
 				res.setHeader("Content-Type", "application/json; charset=utf-8");
@@ -957,17 +1480,28 @@ function routes(input = "src/pages") {
 				if (![
 					"/__vite-file-router-data",
 					"/__vite-file-router-events",
-					"/__vite-file-router-match"
+					"/__vite-file-router-match",
+					"/__vite-file-router-navigate",
+					"/__vite-file-router-code"
 				].includes(url.pathname)) {
 					next();
 					return;
 				}
-				if (req.method !== "GET") {
+				const method = url.pathname === "/__vite-file-router-navigate" ? "POST" : "GET";
+				if (req.method !== method) {
 					res.statusCode = 405;
-					res.setHeader("Allow", "GET");
+					res.setHeader("Allow", method);
 					res.end("Method Not Allowed");
 					return;
 				}
+				if (url.pathname === "/__vite-file-router-code") {
+					getGeneratedCode().then((modules) => sendJson(res, { modules }), next);
+					return;
+				}
+				if (url.pathname === "/__vite-file-router-navigate") {
+					navigateApp(req, res);
+					return;
+				}
 				if (url.pathname === "/__vite-file-router-data") {
 					sendJson(res, getInspectorState());
 					return;
@@ -1020,4 +1554,4 @@ function routes(input = "src/pages") {
 		}
 	};
 }
-export { routes };
+export { formatRouteWarnings, routes };