@troyio/vite-file-router 0.3.2 → 0.4.1

package/dist/index.js

@@ -1,8 +1,8 @@
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { genArrayFromRaw, genObjectFromRaw, genSafeVariableName } from "knitwork";
 import { format } from "prettier";
-import fs from "node:fs";
 // src/scanner.ts
 var DEFAULT_CONVENTIONS = {
 	page: "page",
@@ -35,11 +35,17 @@ function getRouteParameter(name) {
 		optional: false
 	} : void 0;
 }
-function collectPageRoutePatterns(node, segments = [], root = true) {
+function collectPageRoutes(node, segments = [], root = true) {
 	const routeSegments = root || node.routeGroup ? segments : [...segments, getRouteSegment(node.name)];
-	const patterns = node.page ? [`/${routeSegments.join("/")}`] : [];
-	for (const child of node.children) patterns.push(...collectPageRoutePatterns(child, routeSegments, false));
-	return patterns;
+	const pages = node.page ? [{
+		pattern: `/${routeSegments.join("/")}`,
+		node
+	}] : [];
+	for (const child of node.children) pages.push(...collectPageRoutes(child, routeSegments, false));
+	return pages;
+}
+function collectPageRoutePatterns(node) {
+	return collectPageRoutes(node).map(({ pattern }) => pattern);
 }
 function scan(directory, conventions = DEFAULT_CONVENTIONS) {
 	const node = {
@@ -133,15 +139,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        ")}
       };
@@ -154,9 +160,143 @@ 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))})`);
+	const preload = {};
+	if (imports.length) preload.load = `() => Promise.all([${imports.join(", ")}])`;
+	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; only a short text preview
+* of returned data is sent. 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 {}
+}
+
+function previewRouteData(value) {
+  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;
+  } catch {
+    return String(value);
+  }
+}
+
+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 };
+  }
+  if (thrown) {
+    return {
+      outcome: "error",
+      message: value instanceof Error ? value.message : previewRouteData(value),
+    };
+  }
+  return { outcome: "data", preview: previewRouteData(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;
+    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),
+      });
+    try {
+      const result = await handler(args);
+      report(result, false);
+      return result;
+    } catch (error) {
+      report(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,
+      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);
+  }
+  // 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("/") || "."}`;
 }
@@ -170,7 +310,7 @@ 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));
 	let loadingComponent;
 	if (node.loading) {
 		loadingComponent = genSafeVariableName(`Loading${context.nextLoadingId++}`);
@@ -183,21 +323,27 @@ 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));
+	}
+	for (const child of node.children) {
+		const generated = generateNode(child, false, context, hasBoundary);
+		children.push(generated.route);
+		preloadChildren.push(generated.preload);
 	}
-	for (const child of node.children) children.push(generateNode(child, false, context, hasBoundary));
 	if (node.notFound) {
 		const notFoundRoute = hasBoundary ? {
 			path: JSON.stringify("*"),
@@ -207,11 +353,15 @@ function generateNode(node, root, context, inheritedBoundary) {
 			lazy: generateImport(node.notFound, context.projectRoot)
 		};
 		children.push(genObjectFromRaw(notFoundRoute));
+		preloadChildren.push(generatePreload([node.notFound], context.projectRoot));
 	}
 	if (children.length) route.children = genArrayFromRaw(children);
-	return genObjectFromRaw(route);
+	return {
+		route: genObjectFromRaw(route),
+		preload: generatePreload([node.layout, node.loader], 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);
@@ -221,9 +371,10 @@ function generate(node, root = false, projectRoot = process.cwd()) {
 		nextLoadingId: 0,
 		hasBoundaries: false,
 		hasLayouts: false,
-		hasErrorBoundaries: false
+		hasErrorBoundaries: false,
+		devClient: Boolean(options.devClient)
 	};
-	const routes = generateNode(node, root, context, false);
+	const { route: routes, preload: preloads } = generateNode(node, root, context, false);
 	const imports = [...context.loadingImports];
 	const helpers = [];
 	if (context.hasBoundaries || context.hasLayouts || context.hasErrorBoundaries) {
@@ -232,8 +383,10 @@ function generate(node, root = false, projectRoot = process.cwd()) {
 		if (context.hasBoundaries || context.hasLayouts || context.hasErrorBoundaries) reactImports.push("lazy");
 		if (context.hasBoundaries || context.hasErrorBoundaries) reactImports.push("Suspense");
 		imports.unshift(`import { ${reactImports.join(", ")} } from "react";`);
-		if (context.hasBoundaries || context.hasLayouts) imports.push(`import { Outlet } from "react-router";`);
 	}
+	const routerImports = ["matchRoutes"];
+	if (context.hasBoundaries || context.hasLayouts) routerImports.push("Outlet");
+	imports.push(`import { ${routerImports.join(", ")} } from "react-router";`);
 	if (context.hasBoundaries) helpers.push(`function createBoundary(Fallback, Component) {
   return function RouteBoundary() {
     return createElement(
@@ -257,10 +410,275 @@ function generate(node, root = false, projectRoot = process.cwd()) {
     );
   };
 }`);
+	if (context.devClient) helpers.push(DEVTOOLS_CLIENT);
 	return {
 		imports,
 		helpers,
-		routes
+		routes,
+		preloads
+	};
+}
+// src/declarations.ts
+var PACKAGE_NAME = "@troyio/vite-file-router";
+function collectLoaders(node, loaders = []) {
+	if (node.loader) loaders.push(node);
+	for (const child of node.children) collectLoaders(child, loaders);
+	return loaders;
+}
+function getTypeImportPath(file, declarationFile) {
+	const relativePath = path.relative(path.dirname(declarationFile), file).split(path.sep).join("/").replace(/\.ts$/, "");
+	return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+/**
+* Builds a declaration file that registers the discovered page patterns and
+* loader modules with the package's `Register` interface. The package's
+* public types read from that interface, so `routePath()` and the typed hooks
+* only accept routes that exist.
+*/
+function createRouteDeclarations(tree, projectRoot, declarationFile) {
+	const routes = /* @__PURE__ */ new Map();
+	for (const { pattern, node } of collectPageRoutes(tree)) {
+		if (routes.has(pattern)) continue;
+		routes.set(pattern, node.loader ? getRouteId(node.directory, projectRoot) : null);
+	}
+	const routeLines = [...routes.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([pattern, loader]) => `      ${JSON.stringify(pattern)}: { loader: ${loader === null ? "null" : JSON.stringify(loader)} };`);
+	const loaderLines = collectLoaders(tree).map((node) => {
+		const id = getRouteId(node.directory, projectRoot);
+		const file = node.loader;
+		const moduleType = file.endsWith(".ts") ? `typeof import(${JSON.stringify(getTypeImportPath(file, declarationFile))})` : "{ loader: (...args: any[]) => any }";
+		return [id, `      ${JSON.stringify(id)}: ${moduleType};`];
+	}).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([, line]) => line);
+	return [
+		`// Generated by ${PACKAGE_NAME}. Do not edit this file.`,
+		"// It is rewritten whenever route files are added, removed, or renamed.",
+		"",
+		"export {};",
+		"",
+		`declare module ${JSON.stringify(PACKAGE_NAME)} {`,
+		"  interface Register {",
+		routeLines.length ? [
+			"    routes: {",
+			...routeLines,
+			"    };"
+		].join("\n") : "    routes: {};",
+		loaderLines.length ? [
+			"    loaders: {",
+			...loaderLines,
+			"    };"
+		].join("\n") : "    loaders: {};",
+		"  }",
+		"}",
+		""
+	].join("\n");
+}
+// src/devtools.ts
+var ROUTE_INSPECTOR_PATH = "/__vite-file-router/";
+var HEARTBEAT_INTERVAL = 25e3;
+/**
+* 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"),
+		...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";
+var MAX_ACTIVITY = 200;
+var MAX_TEXT = 600;
+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;
+}
+/**
+* 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 !== "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 } : {},
+		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 } : {}
+	};
+}
+/**
+* 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();
+		},
+		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
@@ -270,12 +688,17 @@ 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 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") throw new TypeError(`Unknown routes() option "${key}".`);
+	for (const key of Object.keys(options)) if (key !== "directory" && key !== "conventions" && key !== "dts") 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 };
@@ -287,9 +710,12 @@ 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 ?? "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
+		conventions,
+		dts
 	};
 }
 function routes(input = "src/pages") {
@@ -297,6 +723,32 @@ function routes(input = "src/pages") {
 	let projectRoot = "";
 	let root = "";
 	let dev = false;
+	let declarationFile;
+	function getInspectorState() {
+		const tree = scan(root, options.conventions);
+		return {
+			projectRoot,
+			directory: path.relative(projectRoot, root).split(path.sep).join("/"),
+			manifest: createRouteManifest(tree, projectRoot),
+			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);
+		if (fs.existsSync(declarationFile) && fs.readFileSync(declarationFile, "utf8") === content) return;
+		fs.mkdirSync(path.dirname(declarationFile), { recursive: true });
+		fs.writeFileSync(declarationFile, content);
+	}
 	function sortImports(imports) {
 		return imports.sort((left, right) => {
 			const leftSource = left.match(/from ["'](.+?)["']/)?.[1] ?? left;
@@ -328,14 +780,41 @@ function routes(input = "src/pages") {
         }
 
         export const routes = [{ path: "*", Component: RouteConflictPage }];
+
+        export async function preloadRoute() {
+          return false;
+        }
       `;
 			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"),
-			`export const routes = ${genArrayFromRaw([generated.routes])};`
+			`export const routes = ${genArrayFromRaw([generated.routes])};`,
+			`const preloadTree = ${genArrayFromRaw([generated.preloads])};
+      const routePreloads = new WeakMap();
+
+      function registerPreloads(routeList, preloadList) {
+        routeList.forEach((route, index) => {
+          const preload = preloadList[index];
+          if (preload?.load) routePreloads.set(route, preload.load);
+          if (route.children) {
+            registerPreloads(route.children, preload?.children ?? []);
+          }
+        });
+      }
+
+      registerPreloads(routes, preloadTree);
+
+      export async function preloadRoute(to, basename) {
+        const matches = matchRoutes(routes, to, basename);
+        if (!matches) return false;
+        await Promise.all(
+          matches.map(({ route }) => routePreloads.get(route)?.()),
+        );
+        return true;
+      }`
 		].filter(Boolean);
 		return format(sections.join("\n\n"), { parser: "typescript" });
 	}
@@ -346,8 +825,35 @@ function routes(input = "src/pages") {
 	async function executeRouteHelpers() {
 		const tree = scan(root, options.conventions);
 		const patterns = [...new Set(collectPageRoutePatterns(tree))].sort();
+		const routeLoaderIds = {};
+		for (const { pattern, node } of collectPageRoutes(tree)) if (node.loader && !Object.hasOwn(routeLoaderIds, pattern)) routeLoaderIds[pattern] = getRouteId(node.directory, projectRoot);
+		const collectLoaderIds = (node) => {
+			if (node.loader) {
+				const id = getRouteId(node.directory, projectRoot);
+				routeLoaderIds[id] = id;
+			}
+			node.children.forEach(collectLoaderIds);
+		};
+		collectLoaderIds(tree);
 		const code = `
+      import { useParams, useRouteLoaderData } from "react-router";
+
       export const routePatterns = ${JSON.stringify(patterns)};
+      const routeLoaderIds = ${JSON.stringify(routeLoaderIds)};
+
+      export function useRouteParams(pattern) {
+        if (!routePatterns.includes(pattern)) {
+          throw new TypeError(\`Unknown route pattern "\${pattern}".\`);
+        }
+        return useParams();
+      }
+
+      export function useRouteData(key) {
+        if (!Object.hasOwn(routeLoaderIds, key)) {
+          throw new TypeError(\`Route "\${key}" has no loader.\`);
+        }
+        return useRouteLoaderData(routeLoaderIds[key]);
+      }
 
       export function routePath(pattern, ...args) {
         if (!routePatterns.includes(pattern)) {
@@ -415,6 +921,10 @@ function routes(input = "src/pages") {
 			projectRoot = config.root;
 			root = path.resolve(projectRoot, options.directory);
 			dev = config.command === "serve";
+			declarationFile = resolveDeclarationFile(options.dts, projectRoot);
+		},
+		buildStart() {
+			writeDeclarations();
 		},
 		resolveId: (id) => {
 			if (id === ROUTES_MODULE_ID) return ROUTES_RESOLVED_ID;
@@ -436,8 +946,19 @@ function routes(input = "src/pages") {
 				type: "iframe",
 				url: ROUTE_INSPECTOR_PATH
 			});
+			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"
+				].includes(url.pathname)) {
 					next();
 					return;
 				}
@@ -447,11 +968,21 @@ function routes(input = "src/pages") {
 					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-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) => {
@@ -475,8 +1006,17 @@ function routes(input = "src/pages") {
 					const module = server.moduleGraph.getModuleById(id);
 					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);
+			});
 		}
 	};
 }