@troyio/vite-file-router 0.4.0 → 0.5.0

package/dist/index.js

@@ -11,7 +11,8 @@ var DEFAULT_CONVENTIONS = {
 	notFound: "not-found",
 	error: "error",
 	loader: "loader",
-	action: "action"
+	action: "action",
+	middleware: "middleware"
 };
 function getRouteSegment(name) {
 	if (name.startsWith("[...") && name.endsWith("]")) return "*";
@@ -68,7 +69,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;
@@ -139,15 +140,15 @@ function generateImport(file, projectRoot) {
     Component: (await import(${JSON.stringify(getImportPath(file, projectRoot))})).default
   })`;
 }
-function generateRouteLazy(node, projectRoot, includeLayout, includeLoader) {
+function generateRouteLazy(node, projectRoot, includeLayout, includeLoader, instrumentId) {
 	const properties = [];
 	if (includeLayout && node.layout) properties.push(`Component: withOutlet((await import(${JSON.stringify(getImportPath(node.layout, projectRoot))})).default)`);
 	if (includeLoader && node.loader) return `async () => {
       const loaderModule = await import(${JSON.stringify(getImportPath(node.loader, projectRoot))});
       return {
-        loader: loaderModule.loader,
+        loader: ${instrumentId ? `instrumentRouteData("loader", ${JSON.stringify(instrumentId)}, loaderModule.loader)` : "loaderModule.loader"},
         ...(typeof loaderModule.shouldRevalidate === "function"
-          ? { shouldRevalidate: loaderModule.shouldRevalidate }
+          ? { shouldRevalidate: ${instrumentId ? `instrumentRevalidate(${JSON.stringify(instrumentId)}, loaderModule.shouldRevalidate)` : "loaderModule.shouldRevalidate"} }
           : {}),
         ${properties.join(",\n        ")}
       };
@@ -160,8 +161,12 @@ function generateLazyComponent(file, projectRoot) {
 function generateLazyLayout(file, projectRoot) {
 	return `lazy(() => import(${JSON.stringify(getImportPath(file, projectRoot))}).then(({ default: Layout }) => ({ default: withOutlet(Layout) })))`;
 }
-function generateDataHandler(file, projectRoot) {
-	return `async (args) => (await import(${JSON.stringify(getImportPath(file, projectRoot))})).action(args)`;
+function generateDataHandler(file, projectRoot, instrumentId) {
+	const handler = `async (args) => (await import(${JSON.stringify(getImportPath(file, projectRoot))})).action(args)`;
+	return instrumentId ? `instrumentRouteData("action", ${JSON.stringify(instrumentId)}, ${handler})` : handler;
+}
+function getInstrumentId(node, context) {
+	return context.devClient ? getRouteId(node.directory, context.projectRoot) : void 0;
 }
 function generatePreload(files, projectRoot, children = []) {
 	const imports = files.filter((file) => Boolean(file)).map((file) => `import(${JSON.stringify(getImportPath(file, projectRoot))})`);
@@ -170,6 +175,337 @@ function generatePreload(files, projectRoot, children = []) {
 	if (children.length) preload.children = genArrayFromRaw(children);
 	return genObjectFromRaw(preload);
 }
+/**
+* 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; 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;
+const devtoolsTabId = Math.random().toString(36).slice(2, 10);
+
+function sendToDevtools(event, payload) {
+  try {
+    devtoolsHot?.send(event, { ...payload, tabId: devtoolsTabId });
+  } 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 {
+    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 undefined;
+  }
+}
+
+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: previewRouteData(value),
+      ...serializeRouteData(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) {
+  if (!devtoolsHot || typeof handler !== "function") return handler;
+  return async (args) => {
+    const startedAt = Date.now();
+    const started = performance.now();
+    const request = args?.request;
+    // 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);
+      return result;
+    } catch (error) {
+      report(error, true);
+      throw error;
+    }
+  };
+}
+
+// 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) => {
+    const decision = shouldRevalidate(args);
+    sendToDevtools("vite-file-router:data", {
+      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,
+    });
+    return decision;
+  };
+}
+
+if (devtoolsHot) {
+  let reportedUrl;
+  const currentUrl = () =>
+    window.location.hash.startsWith("#/")
+      ? window.location.hash.slice(1)
+      : window.location.pathname + window.location.search;
+  const reportLocation = () => {
+    const url = currentUrl();
+    if (url === reportedUrl) return;
+    reportedUrl = url;
+    sendToDevtools("vite-file-router:location", { url, title: document.title });
+  };
+  // React Router's browser router navigates with pushState and replaceState,
+  // which fire no event, so they're wrapped once per page.
+  if (!window.__viteFileRouterHistoryPatched) {
+    window.__viteFileRouterHistoryPatched = true;
+    for (const method of ["pushState", "replaceState"]) {
+      const original = history[method];
+      history[method] = function (...args) {
+        const result = original.apply(this, args);
+        window.dispatchEvent(new Event("vite-file-router:navigate"));
+        return result;
+      };
+    }
+  }
+  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;
+    reportLocation();
+  });
+  reportLocation();
+}`;
 function getRouteId(directory, projectRoot) {
 	return `file-route:${path.relative(projectRoot, directory).split(path.sep).join("/") || "."}`;
 }
@@ -183,7 +519,13 @@ function generateNode(node, root, context, inheritedBoundary) {
 		context.hasErrorBoundaries = true;
 		route.ErrorBoundary = `createErrorBoundary(${generateLazyComponent(node.error, context.projectRoot)})`;
 	}
-	if (node.action) route.action = generateDataHandler(node.action, 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}]`;
+	}
 	let loadingComponent;
 	if (node.loading) {
 		loadingComponent = genSafeVariableName(`Loading${context.nextLoadingId++}`);
@@ -196,18 +538,18 @@ function generateNode(node, root, context, inheritedBoundary) {
 	} else if (node.layout) {
 		if (hasBoundary) route.Component = generateLazyLayout(node.layout, context.projectRoot);
 	}
-	if (node.layout && !hasBoundary || node.loader) route.lazy = generateRouteLazy(node, context.projectRoot, Boolean(node.layout && !hasBoundary), Boolean(node.loader));
+	if (node.layout && !hasBoundary || node.loader) route.lazy = generateRouteLazy(node, context.projectRoot, Boolean(node.layout && !hasBoundary), Boolean(node.loader), node.loader ? getInstrumentId(node, context) : void 0);
 	const children = [];
 	const preloadChildren = [];
 	if (node.page) {
 		const page = hasBoundary ? {
 			index: "true",
 			Component: generateLazyComponent(node.page, context.projectRoot),
-			...node.action ? { action: generateDataHandler(node.action, context.projectRoot) } : {}
+			...node.action ? { action: generateDataHandler(node.action, context.projectRoot, getInstrumentId(node, context)) } : {}
 		} : {
 			index: "true",
 			lazy: generateImport(node.page, context.projectRoot),
-			...node.action ? { action: generateDataHandler(node.action, context.projectRoot) } : {}
+			...node.action ? { action: generateDataHandler(node.action, context.projectRoot, getInstrumentId(node, context)) } : {}
 		};
 		children.push(genObjectFromRaw(page));
 		preloadChildren.push(generatePreload([node.page], context.projectRoot));
@@ -231,10 +573,14 @@ 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()) {
+function generate(node, root = false, projectRoot = process.cwd(), options = {}) {
 	validateRouteGroupNotFound(node, [], root);
 	const conflicts = findPageRouteConflicts(node, /* @__PURE__ */ new Map(), [], root);
 	if (conflicts.length) throw new RouteConflictError(conflicts);
@@ -244,7 +590,9 @@ function generate(node, root = false, projectRoot = process.cwd()) {
 		nextLoadingId: 0,
 		hasBoundaries: false,
 		hasLayouts: false,
-		hasErrorBoundaries: false
+		hasErrorBoundaries: false,
+		hasMiddleware: false,
+		devClient: Boolean(options.devClient)
 	};
 	const { route: routes, preload: preloads } = generateNode(node, root, context, false);
 	const imports = [...context.loadingImports];
@@ -282,6 +630,32 @@ function generate(node, root = false, projectRoot = process.cwd()) {
     );
   };
 }`);
+	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 {
 		imports,
 		helpers,
@@ -342,6 +716,340 @@ function createRouteDeclarations(tree, projectRoot, declarationFile) {
 		""
 	].join("\n");
 }
+// 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
+* page, so matching agrees with the runtime routes.
+*/
+function toMatchableRoute(node) {
+	const children = [];
+	if (node.files.page) children.push({
+		index: true,
+		node,
+		kind: "page"
+	});
+	for (const child of node.children) children.push(toMatchableRoute(child));
+	if (node.files.notFound) children.push({
+		path: "*",
+		node,
+		kind: "notFound"
+	});
+	return {
+		...node.segment === null ? {} : { path: node.segment },
+		node,
+		...children.length ? { children } : {}
+	};
+}
+async function matchRouteManifest(manifest, url) {
+	const { matchRoutes } = await import("react-router");
+	const pathname = new URL(url, "http://vite-file-router").pathname;
+	const matches = matchRoutes([toMatchableRoute(manifest)], pathname);
+	if (!matches) return {
+		matched: false,
+		pathname
+	};
+	const leaf = matches[matches.length - 1].route;
+	const chain = matches.filter(({ route }) => !route.kind).map(({ route }) => route.node);
+	const nearest = (kind) => [...chain].reverse().find((node) => node.files[kind])?.files[kind];
+	const collect = (kind) => chain.flatMap((node) => node.files[kind] ? [node.files[kind]] : []);
+	return {
+		matched: true,
+		pathname,
+		params: matches[matches.length - 1].params,
+		chain: chain.map(({ fullPath, segment, routeGroup, files }) => ({
+			fullPath,
+			segment,
+			routeGroup,
+			files
+		})),
+		...leaf.kind === "page" ? { page: leaf.node?.files.page } : {},
+		...leaf.kind === "notFound" ? { notFound: leaf.node?.files.notFound } : {},
+		layouts: collect("layout"),
+		loaders: collect("loader"),
+		middleware: collect("middleware"),
+		...nearest("loading") ? { loading: nearest("loading") } : {},
+		...nearest("error") ? { error: nearest("error") } : {}
+	};
+}
+function writeEvent(response, event, data) {
+	response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+}
+/** Pushes route state to open DevTools panels over Server-Sent Events. */
+function createRouteEventStream(getState, getSnapshot = () => []) {
+	const clients = /* @__PURE__ */ new Set();
+	let pending;
+	function send(response) {
+		writeEvent(response, "routes", getState());
+	}
+	return {
+		clients,
+		connect(request, response) {
+			response.statusCode = 200;
+			response.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+			response.setHeader("Cache-Control", "no-store");
+			response.setHeader("Connection", "keep-alive");
+			response.flushHeaders?.();
+			response.write("retry: 1000\n\n");
+			send(response);
+			for (const [event, data] of getSnapshot()) writeEvent(response, event, data);
+			clients.add(response);
+			const heartbeat = setInterval(() => response.write(": heartbeat\n\n"), HEARTBEAT_INTERVAL);
+			heartbeat.unref?.();
+			request.on("close", () => {
+				clearInterval(heartbeat);
+				clients.delete(response);
+			});
+		},
+		/** Coalesces bursts of file events (such as a folder rename) into one push. */
+		notify() {
+			if (!clients.size) return;
+			clearTimeout(pending);
+			pending = setTimeout(() => {
+				pending = void 0;
+				for (const client of clients) send(client);
+			}, 50);
+		},
+		/** Sends a named event to every connected panel right away. */
+		broadcast(event, data) {
+			for (const client of clients) writeEvent(client, event, data);
+		},
+		close() {
+			clearTimeout(pending);
+			for (const client of clients) client.end();
+			clients.clear();
+		}
+	};
+}
+// src/devtools-app.ts
+/** 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;
+}
+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.
+*/
+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 !== "middleware" && type !== "revalidate") return;
+	const routeId = text(event.routeId, 400);
+	const tabId = text(event.tabId, 100);
+	if (!routeId || !tabId) return void 0;
+	const outcome = event.outcome;
+	return {
+		id,
+		tabId,
+		type,
+		routeId,
+		url: text(event.url, 2e3),
+		method: text(event.method, 20),
+		startedAt: finite(event.startedAt) ?? Date.now(),
+		duration: finite(event.duration),
+		...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 } : {},
+		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)
+	};
+}
+/**
+* Tracks the app tabs connected to the dev server and their recent loader
+* and action calls, and tells the panel when either changes.
+*/
+function createAppTracker(options) {
+	const tabs = /* @__PURE__ */ new Map();
+	const latestReport = /* @__PURE__ */ new Map();
+	const activity = [];
+	let nextEventId = 1;
+	let nextReport = 1;
+	const list = () => [...tabs.values()].sort((a, b) => a.connectedAt - b.connectedAt);
+	const changed = () => options.onTabsChange(list());
+	return {
+		tabs: list,
+		activity: () => [...activity],
+		async updateLocation(client, input) {
+			if (!input || typeof input !== "object") return;
+			const payload = input;
+			const id = text(payload.tabId, 100);
+			const url = text(payload.url, 2e3);
+			if (!id || !url?.startsWith("/")) return;
+			const report = nextReport++;
+			latestReport.set(client, report);
+			const match = await matchRouteManifest(options.getManifest(), url);
+			if (latestReport.get(client) !== report) return;
+			const now = Date.now();
+			tabs.set(client, {
+				id,
+				url,
+				title: text(payload.title, 200) ?? "",
+				connectedAt: tabs.get(client)?.connectedAt ?? now,
+				updatedAt: now,
+				match
+			});
+			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();
+		},
+		/** Re-matches every tab, for example after route files change. */
+		async rematch() {
+			if (!tabs.size) return;
+			const manifest = options.getManifest();
+			for (const [client, tab] of tabs) tabs.set(client, {
+				...tab,
+				match: await matchRouteManifest(manifest, tab.url)
+			});
+			changed();
+		},
+		record(input) {
+			const event = sanitizeDataEvent(input, nextEventId);
+			if (!event) return;
+			nextEventId++;
+			activity.push(event);
+			if (activity.length > MAX_ACTIVITY) activity.shift();
+			options.onActivity(event);
+		}
+	};
+}
 // src/index.ts
 var ROUTES_MODULE_ID = "virtual:routes";
 var ROUTES_RESOLVED_ID = `\0${ROUTES_MODULE_ID}`;
@@ -349,13 +1057,22 @@ 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 ROUTE_INSPECTOR_PATH = "/__vite-file-router/";
-var ROUTE_INSPECTOR_DATA_PATH = "/__vite-file-router-data";
+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) {
+	if (dts === false) return void 0;
+	if (dts !== "auto") return path.resolve(projectRoot, dts);
+	return TYPESCRIPT_CONFIG_FILES.some((file) => fs.existsSync(path.join(projectRoot, file))) ? path.resolve(projectRoot, DEFAULT_DTS) : void 0;
+}
 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 };
@@ -367,13 +1084,51 @@ function resolveOptions(input) {
 	}
 	const names = Object.values(conventions);
 	if (new Set(names).size !== names.length) throw new TypeError("Route file convention names must be unique.");
-	const dts = options.dts ?? DEFAULT_DTS;
-	if (dts !== false && (typeof dts !== "string" || dts.trim() === "" || !dts.endsWith(".d.ts"))) throw new TypeError("routes() dts must be false or a path ending in \".d.ts\".");
+	const dts = options.dts ?? "auto";
+	if (dts !== false && dts !== "auto" && (typeof dts !== "string" || dts.trim() === "" || !dts.endsWith(".d.ts"))) throw new TypeError("routes() dts must be \"auto\", false, or a path ending in \".d.ts\".");
 	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);
@@ -381,6 +1136,45 @@ function routes(input = "src/pages") {
 	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,
+			warnings: findRouteWarnings(manifest, readSource),
+			conflicts: findPageRouteConflicts(tree).map(({ routePath, files }) => ({
+				routePath,
+				files: files.map((file) => path.relative(projectRoot, file).split(path.sep).join("/"))
+			}))
+		};
+	}
+	const appTracker = createAppTracker({
+		getManifest: () => createRouteManifest(scan(root, options.conventions), projectRoot),
+		onTabsChange: (tabs) => routeEvents.broadcast("apps", tabs),
+		onActivity: (event) => routeEvents.broadcast("activity", event)
+	});
+	const routeEvents = createRouteEventStream(getInspectorState, () => [["apps", appTracker.tabs()], ["activity-snapshot", appTracker.activity()]]);
 	function writeDeclarations() {
 		if (!declarationFile) return;
 		const content = createRouteDeclarations(scan(root, options.conventions), projectRoot, declarationFile);
@@ -426,7 +1220,7 @@ function routes(input = "src/pages") {
       `;
 			return format(code, { parser: "typescript" });
 		}
-		const generated = generate(tree, true, projectRoot);
+		const generated = generate(tree, true, projectRoot, { devClient: dev });
 		const sections = [
 			sortImports(generated.imports).join("\n"),
 			generated.helpers.join("\n"),
@@ -560,10 +1354,17 @@ function routes(input = "src/pages") {
 			projectRoot = config.root;
 			root = path.resolve(projectRoot, options.directory);
 			dev = config.command === "serve";
-			declarationFile = options.dts === false ? void 0 : path.resolve(projectRoot, options.dts);
+			declarationFile = resolveDeclarationFile(options.dts, projectRoot);
 		},
 		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;
@@ -585,22 +1386,86 @@ 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");
+				res.setHeader("Cache-Control", "no-store");
+				res.end(JSON.stringify(body));
+			};
 			ctx.viteServer.middlewares.use((req, res, next) => {
-				if (new URL(req.url ?? "/", "http://vite-file-router").pathname !== ROUTE_INSPECTOR_DATA_PATH) {
+				const url = new URL(req.url ?? "/", "http://vite-file-router");
+				if (![
+					"/__vite-file-router-data",
+					"/__vite-file-router-events",
+					"/__vite-file-router-match",
+					"/__vite-file-router-navigate"
+				].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;
 				}
-				const manifest = createRouteManifest(scan(root, options.conventions), projectRoot);
-				res.statusCode = 200;
-				res.setHeader("Content-Type", "application/json; charset=utf-8");
-				res.setHeader("Cache-Control", "no-store");
-				res.end(JSON.stringify(manifest));
+				if (url.pathname === "/__vite-file-router-navigate") {
+					navigateApp(req, res);
+					return;
+				}
+				if (url.pathname === "/__vite-file-router-data") {
+					sendJson(res, getInspectorState());
+					return;
+				}
+				if (url.pathname === "/__vite-file-router-events") {
+					routeEvents.connect(req, res);
+					return;
+				}
+				const target = url.searchParams.get("url");
+				if (!target) {
+					res.statusCode = 400;
+					res.end("Missing \"url\" query parameter.");
+					return;
+				}
+				matchRouteManifest(createRouteManifest(scan(root, options.conventions), projectRoot), target).then((result) => sendJson(res, result), next);
 			});
 		} },
 		configureServer: (server) => {
@@ -625,9 +1490,17 @@ function routes(input = "src/pages") {
 					if (module) server.moduleGraph.invalidateModule(module);
 				}
 				writeDeclarations();
+				routeEvents.notify();
+				appTracker.rematch();
 				server.ws.send({ type: "full-reload" });
 			});
+			server.httpServer?.on("close", routeEvents.close);
+			server.ws.on(APP_LOCATION_EVENT, (data, client) => appTracker.updateLocation(client, data).catch(() => {}));
+			server.ws.on(APP_DATA_EVENT, (data) => appTracker.record(data));
+			server.ws.on("vite:client:disconnect", (_data, client) => {
+				appTracker.disconnect(client);
+			});
 		}
 	};
 }
-export { routes };
+export { formatRouteWarnings, routes };