@troyio/vite-file-router 0.3.2 → 0.4.0

package/README.md

@@ -249,6 +249,10 @@ export default function DashboardPage() {
 }
 ```
 
+To get the type from the loader module instead of writing it by hand, use
+`useRouteData` from `virtual:route-helpers`. See
+[Typed params and loader data](#typed-params-and-loader-data).
+
 The authentication and mutation functions above are application code. A
 client-side route guard controls navigation and presentation; it is not a
 security boundary. Protect data and mutations in the server/API layer as well,
@@ -360,6 +364,97 @@ parameters are rejected at runtime. Routes whose optional segment overlaps
 another page's URL pattern are reported as conflicts. The generated
 `routePatterns` export contains the discovered page paths.
 
+### Generated route types
+
+When the dev server starts and at the start of each build, the plugin writes
+`src/route-types.d.ts`. It rewrites the file whenever route files are added,
+removed, or renamed, and leaves it alone when nothing changed. The file lists
+every discovered page pattern and loader module. With it in your TypeScript
+project, `routePath`, `routePatterns`, and the hooks below only accept routes
+that exist, and your editor autocompletes them:
+
+```ts
+routePath("/users/:userId", { userId }); // OK
+routePath("/usres/:userId", { userId }); // Type error: unknown route pattern
+```
+
+Change the output path, or turn the file off, with the `dts` option. The path
+is relative to the Vite project root and must end in `.d.ts`:
+
+```ts
+plugins: [routes({ dts: "types/route-types.d.ts" })];
+plugins: [routes({ dts: false })];
+```
+
+Without the file, route patterns are typed as `string` and loader data as
+`unknown`, the same as before. You can commit the file so types work before
+the first dev run, or add it to `.gitignore`.
+
+### Typed params and loader data
+
+`virtual:route-helpers` also exports two hooks that wrap React Router's hooks
+with types taken from the route tree:
+
+- `useRouteParams(pattern)` returns `useParams()`, typed for that pattern.
+  Required params are `string`, optional params are `string | undefined`, and
+  a splat is a `string` under the `"*"` key.
+- `useRouteData(key)` returns `useRouteLoaderData()`, typed from the loader
+  module. The key is either a page pattern, which reads the loader in that
+  page's directory, or a loader route ID such as
+  `"file-route:src/pages/users/[userId]"`, which can read any matched loader,
+  including a parent's. It returns `undefined` when that route isn't matched,
+  just like React Router's hook.
+
+```tsx
+// src/pages/users/[userId]/loader.ts
+import type { LoaderFunctionArgs } from "react-router";
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  return { name: await getUserName(params.userId!) };
+}
+
+// src/pages/users/[userId]/page.tsx
+import { useRouteData, useRouteParams } from "virtual:route-helpers";
+
+export default function UserPage() {
+  const { userId } = useRouteParams("/users/:userId"); // { userId: string }
+  const data = useRouteData("/users/:userId"); // { name: string } | undefined
+  return <h1>{data?.name ?? userId}</h1>;
+}
+```
+
+The `RouteParams<"/users/:userId">`, `RouteLoaderData<key>`, `RoutePattern`,
+and `RouteLoaderKey` types are exported from `@troyio/vite-file-router` for
+your own helpers. Loader data is typed the same way as React Router's
+`useRouteLoaderData<typeof loader>()`. JavaScript loader modules are typed as
+`any`. Both hooks throw if they're passed a pattern or key the plugin didn't
+discover.
+
+### Route preloading
+
+`virtual:routes` exports `preloadRoute(to, basename?)`. It matches a URL
+against the route tree and imports the page, layout, and loader modules of
+every matched route, so the next navigation there doesn't wait for those
+downloads. Error and action modules are left out, since they're only needed
+after an error or a form submission. Importing modules doesn't run loaders.
+Each module downloads once, however often you call it. The promise resolves to
+`false` when no route matches the URL.
+
+Call it when a user is likely to navigate, such as on link hover or focus:
+
+```tsx
+import { Link, type LinkProps } from "react-router";
+import { preloadRoute } from "virtual:routes";
+
+export function PreloadLink(props: LinkProps & { to: string }) {
+  const preload = () => void preloadRoute(props.to);
+  return <Link {...props} onMouseEnter={preload} onFocus={preload} />;
+}
+```
+
+If the router uses a `basename`, pass it as the second argument. `to` also
+accepts a partial location such as `{ pathname: "/users/42" }`.
+
 ### TypeScript setup
 
 Add Vite's client types and the package's virtual-module declaration to your
@@ -372,8 +467,9 @@ application TypeScript project. For example, create `src/vite-env.d.ts`:
 
 If `tsconfig.json` sets `compilerOptions.types`, include both `"vite/client"`
 and `"@troyio/vite-file-router"` in that list. This lets TypeScript resolve
-`virtual:routes`. Restart your editor's TypeScript server if the declaration
-isn't picked up immediately.
+`virtual:routes`. Make sure the generated `src/route-types.d.ts`, or the path
+you set with `dts`, is included by your `tsconfig.json`. Restart your editor's
+TypeScript server if the declarations aren't picked up immediately.
 
 ## Build
 

package/dist/declarations.d.ts

@@ -0,0 +1,9 @@
+import { type Node } from "./scanner";
+export declare const PACKAGE_NAME = "@troyio/vite-file-router";
+/**
+ * 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.
+ */
+export declare function createRouteDeclarations(tree: Node, projectRoot: string, declarationFile: string): string;

package/dist/generator.d.ts

@@ -3,6 +3,11 @@ export type GeneratedRoutes = {
     imports: string[];
     helpers: string[];
     routes: string;
+    /**
+     * A tree that mirrors `routes`: each node lists the modules a matched route
+     * needs to render, so `preloadRoute()` can import them ahead of navigation.
+     */
+    preloads: string;
 };
 export type RouteConflict = {
     routePath: string;
@@ -13,4 +18,5 @@ export declare class RouteConflictError extends Error {
     constructor(conflicts: RouteConflict[]);
 }
 export declare function findPageRouteConflicts(node: Node, pages?: Map<string, string[]>, segments?: string[], root?: boolean): RouteConflict[];
+export declare function getRouteId(directory: string, projectRoot: string): string;
 export declare function generate(node: Node, root?: boolean, projectRoot?: string): GeneratedRoutes;

package/dist/index.d.ts

@@ -3,6 +3,12 @@ import { type RouteConventions } from "./scanner";
 export type RoutesOptions = {
     directory?: string;
     conventions?: RouteConventions;
+    /**
+     * Where to write the generated route type declarations, relative to the Vite
+     * project root. Set to `false` to skip writing them.
+     * @default "src/route-types.d.ts"
+     */
+    dts?: string | false;
 };
 export type { RouteConventions, RouteFileKind, RouteManifestNode, } from "./scanner";
 export declare function routes(input?: string | RoutesOptions): Plugin;

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 = {
@@ -157,6 +163,13 @@ function generateLazyLayout(file, projectRoot) {
 function generateDataHandler(file, projectRoot) {
 	return `async (args) => (await import(${JSON.stringify(getImportPath(file, projectRoot))})).action(args)`;
 }
+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);
+}
 function getRouteId(directory, projectRoot) {
 	return `file-route:${path.relative(projectRoot, directory).split(path.sep).join("/") || "."}`;
 }
@@ -185,6 +198,7 @@ function generateNode(node, root, context, inheritedBoundary) {
 	}
 	if (node.layout && !hasBoundary || node.loader) route.lazy = generateRouteLazy(node, context.projectRoot, Boolean(node.layout && !hasBoundary), Boolean(node.loader));
 	const children = [];
+	const preloadChildren = [];
 	if (node.page) {
 		const page = hasBoundary ? {
 			index: "true",
@@ -196,8 +210,13 @@ function generateNode(node, root, context, inheritedBoundary) {
 			...node.action ? { action: generateDataHandler(node.action, context.projectRoot) } : {}
 		};
 		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,9 +226,13 @@ 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()) {
 	validateRouteGroupNotFound(node, [], root);
@@ -223,7 +246,7 @@ function generate(node, root = false, projectRoot = process.cwd()) {
 		hasLayouts: false,
 		hasErrorBoundaries: false
 	};
-	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 +255,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(
@@ -260,9 +285,63 @@ function generate(node, root = false, projectRoot = process.cwd()) {
 	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/index.ts
 var ROUTES_MODULE_ID = "virtual:routes";
 var ROUTES_RESOLVED_ID = `\0${ROUTES_MODULE_ID}`;
@@ -272,10 +351,11 @@ 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";
 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 +367,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 ?? 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\".");
 	return {
 		directory,
-		conventions
+		conventions,
+		dts
 	};
 }
 function routes(input = "src/pages") {
@@ -297,6 +380,14 @@ function routes(input = "src/pages") {
 	let projectRoot = "";
 	let root = "";
 	let dev = false;
+	let declarationFile;
+	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,6 +419,10 @@ function routes(input = "src/pages") {
         }
 
         export const routes = [{ path: "*", Component: RouteConflictPage }];
+
+        export async function preloadRoute() {
+          return false;
+        }
       `;
 			return format(code, { parser: "typescript" });
 		}
@@ -335,7 +430,30 @@ function routes(input = "src/pages") {
 		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 +464,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 +560,10 @@ 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);
+		},
+		buildStart() {
+			writeDeclarations();
 		},
 		resolveId: (id) => {
 			if (id === ROUTES_MODULE_ID) return ROUTES_RESOLVED_ID;
@@ -475,6 +624,7 @@ function routes(input = "src/pages") {
 					const module = server.moduleGraph.getModuleById(id);
 					if (module) server.moduleGraph.invalidateModule(module);
 				}
+				writeDeclarations();
 				server.ws.send({ type: "full-reload" });
 			});
 		}

package/dist/scanner.d.ts

@@ -24,6 +24,11 @@ export type RouteManifestNode = {
 };
 export declare const DEFAULT_CONVENTIONS: Record<RouteFileKind, string>;
 export declare function getRouteSegment(name: string): string;
-export declare function collectPageRoutePatterns(node: Node, segments?: string[], root?: boolean): string[];
+export type PageRoute = {
+    pattern: string;
+    node: Node;
+};
+export declare function collectPageRoutes(node: Node, segments?: string[], root?: boolean): PageRoute[];
+export declare function collectPageRoutePatterns(node: Node): string[];
 export declare function scan(directory: string, conventions?: Record<RouteFileKind, string>): Node;
 export declare function createRouteManifest(node: Node, projectRoot: string, parentPath?: string, root?: boolean): RouteManifestNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@troyio/vite-file-router",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "File-system routing plugin for Vite",
   "type": "module",
   "private": false,

package/types/index.d.ts

@@ -1,60 +1,143 @@
-/// <reference path="./virtual-routes.d.ts" />
-
-export { routes } from "../dist/index.js";
-export type {
-  RouteConventions,
-  RouteFileKind,
-  RouteManifestNode,
-  RoutesOptions,
-} from "../dist/index.js";
-
-export type RouteParameterValue = string | number;
-
-type RouteParametersForSegment<Segment extends string> =
-  Segment extends `:${infer Name}?`
-    ? { [Key in Name]?: RouteParameterValue }
-    : Segment extends `:${infer Name}`
-    ? { [Key in Name]: RouteParameterValue }
-    : Segment extends "*"
-      ? { "*": RouteParameterValue }
-      : {};
-
-export type RouteParameters<Path extends string> =
-  Path extends `${infer Segment}/${infer Rest}`
-    ? RouteParametersForSegment<Segment> & RouteParameters<Rest>
-    : RouteParametersForSegment<Path>;
-
-type RouteParameterShapes<Path extends string> =
-  Path extends unknown ? RouteParameters<Path> : never;
-
-type UnionToIntersection<Union> = (
-  Union extends unknown ? (value: Union) => void : never
-) extends (value: infer Intersection) => void
-  ? Intersection
-  : never;
-
-type RouteRequiresParameters<Path extends string> =
-  Path extends unknown
-    ? keyof RouteParameters<Path> extends never
-      ? false
-      : true
-    : never;
-
-type RouteRequiresRequiredParameters<Path extends string> =
-  Path extends unknown ? ({} extends RouteParameters<Path> ? false : true) : never;
-
-type HasParameterShapeMismatch<Path extends string> =
-  [RouteParameterShapes<Path>] extends [
-    UnionToIntersection<RouteParameterShapes<Path>>,
-  ]
-    ? false
-    : true;
-
-export type RoutePathArguments<Path extends string> =
-  true extends RouteRequiresParameters<Path>
-    ? HasParameterShapeMismatch<Path> extends true
-      ? [params: never]
-      : true extends RouteRequiresRequiredParameters<Path>
-        ? [params: RouteParameters<Path>]
-        : [params?: RouteParameters<Path>]
-    : [];
+/// <reference path="./virtual-routes.d.ts" />
+
+import type { useRouteLoaderData } from "react-router";
+
+export { routes } from "../dist/index.js";
+export type {
+  RouteConventions,
+  RouteFileKind,
+  RouteManifestNode,
+  RoutesOptions,
+} from "../dist/index.js";
+
+export type RouteParameterValue = string | number;
+
+type RouteParametersForSegment<Segment extends string> =
+  Segment extends `:${infer Name}?`
+    ? { [Key in Name]?: RouteParameterValue }
+    : Segment extends `:${infer Name}`
+    ? { [Key in Name]: RouteParameterValue }
+    : Segment extends "*"
+      ? { "*": RouteParameterValue }
+      : {};
+
+export type RouteParameters<Path extends string> =
+  Path extends `${infer Segment}/${infer Rest}`
+    ? RouteParametersForSegment<Segment> & RouteParameters<Rest>
+    : RouteParametersForSegment<Path>;
+
+type RouteParameterShapes<Path extends string> =
+  Path extends unknown ? RouteParameters<Path> : never;
+
+type UnionToIntersection<Union> = (
+  Union extends unknown ? (value: Union) => void : never
+) extends (value: infer Intersection) => void
+  ? Intersection
+  : never;
+
+type RouteRequiresParameters<Path extends string> =
+  Path extends unknown
+    ? keyof RouteParameters<Path> extends never
+      ? false
+      : true
+    : never;
+
+type RouteRequiresRequiredParameters<Path extends string> =
+  Path extends unknown ? ({} extends RouteParameters<Path> ? false : true) : never;
+
+type HasParameterShapeMismatch<Path extends string> =
+  [RouteParameterShapes<Path>] extends [
+    UnionToIntersection<RouteParameterShapes<Path>>,
+  ]
+    ? false
+    : true;
+
+export type RoutePathArguments<Path extends string> =
+  true extends RouteRequiresParameters<Path>
+    ? HasParameterShapeMismatch<Path> extends true
+      ? [params: never]
+      : true extends RouteRequiresRequiredParameters<Path>
+        ? [params: RouteParameters<Path>]
+        : [params?: RouteParameters<Path>]
+    : [];
+
+/**
+ * Filled in by the generated route declarations (`src/route-types.d.ts` by
+ * default) through module augmentation. While it is empty, route patterns and
+ * loader keys fall back to `string` and loader data to `unknown`.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by generated code
+export interface Register {}
+
+type RegisteredRoutes = Register extends { routes: infer Routes }
+  ? Routes
+  : never;
+type RegisteredLoaders = Register extends { loaders: infer Loaders }
+  ? Loaders
+  : never;
+type IsRegistered = [RegisteredRoutes] extends [never] ? false : true;
+
+/** A page route pattern discovered from the routes directory. */
+export type RoutePattern = IsRegistered extends true
+  ? Extract<keyof RegisteredRoutes, string>
+  : string;
+
+type PatternsWithLoaders = {
+  [Pattern in keyof RegisteredRoutes]: RegisteredRoutes[Pattern] extends {
+    loader: null;
+  }
+    ? never
+    : Pattern;
+}[keyof RegisteredRoutes];
+
+/**
+ * A page pattern whose directory has a loader, or a loader route ID such as
+ * `"file-route:src/pages/dashboard"`.
+ */
+export type RouteLoaderKey = IsRegistered extends true
+  ? Extract<PatternsWithLoaders | keyof RegisteredLoaders, string>
+  : string;
+
+type LoaderModuleFor<Key> = Key extends keyof RegisteredLoaders
+  ? RegisteredLoaders[Key]
+  : Key extends keyof RegisteredRoutes
+    ? RegisteredRoutes[Key] extends {
+        loader: infer Id extends keyof RegisteredLoaders;
+      }
+      ? RegisteredLoaders[Id]
+      : never
+    : never;
+
+/**
+ * The data a route's loader returns, typed the same way as React Router's
+ * `useRouteLoaderData<typeof loader>()`.
+ */
+export type RouteLoaderData<Key extends string> = IsRegistered extends true
+  ? LoaderModuleFor<Key> extends { loader: infer Loader }
+    ? NonNullable<ReturnType<typeof useRouteLoaderData<Loader>>>
+    : never
+  : unknown;
+
+type Simplify<Value> = { [Key in keyof Value]: Value[Key] } & {};
+
+type RouteParamsForSegment<Segment extends string> =
+  Segment extends `:${infer Name}?`
+    ? { [Key in Name]?: string | undefined }
+    : Segment extends `:${infer Name}`
+      ? { [Key in Name]: string }
+      : Segment extends "*"
+        ? { "*": string }
+        : {};
+
+type RouteParamsIntersection<Path extends string> =
+  Path extends `${infer Segment}/${infer Rest}`
+    ? RouteParamsForSegment<Segment> & RouteParamsIntersection<Rest>
+    : RouteParamsForSegment<Path>;
+
+/**
+ * The params React Router's `useParams()` returns for a route pattern, such
+ * as `RouteParams<"/users/:id">` → `{ id: string }`.
+ */
+export type RouteParams<Path extends string> = Path extends unknown
+  ? Simplify<RouteParamsIntersection<Path>>
+  : never;

package/types/virtual-routes.d.ts

@@ -1,19 +1,46 @@
-declare module "virtual:routes" {
-  import type { RouteObject } from "react-router";
-  export const routes: RouteObject[];
-}
-
-declare module "virtual:route-manifest" {
-  import type { RouteManifestNode } from "@troyio/vite-file-router";
-  export const routeManifest: RouteManifestNode;
-}
-
-declare module "virtual:route-helpers" {
-  import type { RoutePathArguments } from "@troyio/vite-file-router";
-
-  export const routePatterns: readonly string[];
-  export function routePath<const Path extends string>(
-    pattern: Path,
-    ...args: RoutePathArguments<Path>
-  ): string;
-}
+declare module "virtual:routes" {
+  import type { Location, RouteObject } from "react-router";
+  export const routes: RouteObject[];
+  /**
+   * Imports the page, layout, and loader modules for the routes that match a
+   * URL, so a later navigation renders without waiting for them. Resolves to
+   * `false` when no route matches.
+   */
+  export function preloadRoute(
+    to: string | Partial<Location>,
+    basename?: string,
+  ): Promise<boolean>;
+}
+
+declare module "virtual:route-manifest" {
+  import type { RouteManifestNode } from "@troyio/vite-file-router";
+  export const routeManifest: RouteManifestNode;
+}
+
+declare module "virtual:route-helpers" {
+  import type {
+    RouteLoaderData,
+    RouteLoaderKey,
+    RouteParams,
+    RoutePathArguments,
+    RoutePattern,
+  } from "@troyio/vite-file-router";
+
+  export const routePatterns: readonly RoutePattern[];
+  export function routePath<const Path extends RoutePattern>(
+    pattern: Path,
+    ...args: RoutePathArguments<Path>
+  ): string;
+  /** React Router's `useParams()`, typed for the given page pattern. */
+  export function useRouteParams<const Path extends RoutePattern>(
+    pattern: Path,
+  ): RouteParams<Path>;
+  /**
+   * React Router's `useRouteLoaderData()`, typed from the loader module. Pass
+   * a page pattern to read the loader in that page's directory, or a loader
+   * route ID to read any matched loader.
+   */
+  export function useRouteData<const Key extends RouteLoaderKey>(
+    key: Key,
+  ): RouteLoaderData<Key> | undefined;
+}