@troyio/vite-file-router 0.2.6 → 0.2.8

package/README.md

@@ -77,6 +77,9 @@ src/pages/
     page.tsx
     [id]/
       page.tsx
+  docs/
+    [[lang]]/
+      page.tsx
   (auth)/
     layout.tsx
     sign-in/
@@ -87,8 +90,10 @@ src/pages/
     page.tsx
 ```
 
-This maps to `/`, `/users`, `/users/:id`, `/sign-in`, `/sign-up`, and `/*`.
-Square-bracket segments are dynamic parameters: `[id]` becomes `:id`.
+This maps to `/`, `/users`, `/users/:id`, `/docs/:lang?`, `/sign-in`,
+`/sign-up`, and `/*`. Square-bracket segments are dynamic parameters: `[id]`
+becomes `:id`; double-bracket segments are optional dynamic parameters, so
+`[[lang]]` becomes `:lang?` and matches both `/docs` and `/docs/en`.
 Catch-all segments such as `[...slug]` become `*`. Parenthesized directories
 are route groups; they organize files and can have their own page, layout, and
 loading files, but their names do not add a URL segment.
@@ -184,7 +189,8 @@ export default function App() {
 Import `routeManifest` from `virtual:route-manifest` for a stable, nested
 description of the scanned routes. Source files are relative to the Vite
 project root and use forward slashes. Each node includes its URL `fullPath`,
-the parameters introduced by that segment, and its recognized files:
+the parameters introduced by that segment, any `optionalParams`, and its
+recognized files:
 
 ```ts
 import { routeManifest } from "virtual:route-manifest";
@@ -197,8 +203,64 @@ remain in the tree. React Router's generated `routes` remain the runtime source
 of truth.
 
 The development server watches the configured directory. Adding, removing,
-renaming, or editing route files invalidates both virtual modules and reloads
-the app without requiring a server restart.
+renaming, or editing route files invalidates all generated virtual modules and
+reloads the app without requiring a server restart.
+
+### Route tree inspection
+
+The route tree can be inspected in Vite DevTools. This requires Vite 8.3 or
+later and the DevTools package:
+
+```sh
+npm install -D @vitejs/devtools
+```
+
+Enable the dock in your Vite configuration:
+
+```ts
+export default defineConfig({
+  devtools: true,
+  plugins: [routes()],
+});
+```
+
+Open the **Routes** dock to browse the nested route tree, filter by path or
+source file, and inspect parameters and special files. The panel refreshes its
+manifest automatically while the dev server is running. Vite DevTools must be
+enabled; route-tree inspection is development-only.
+
+### Typed route helpers
+
+Import `routePath` from `virtual:route-helpers` to build paths for discovered
+pages. The helper is compatible with React Router's `Link`, `NavLink`,
+`navigate`, and `redirect` APIs. Dynamic parameter names and required values are
+checked from the path literal; values are URL-encoded. Splat values use the
+React Router `"*"` parameter and are encoded segment-by-segment so `/`
+separators are preserved:
+
+```tsx
+import { Link } from "react-router";
+import { routePath } from "virtual:route-helpers";
+
+export function UserLink({ userId }: { userId: string }) {
+  return (
+    <Link to={routePath("/users/:userId", { userId })}>
+      View user
+    </Link>
+  );
+}
+
+const docsPath = routePath("/docs/*", { "*": "guides/getting-started" });
+const localizedDocsPath = routePath("/docs/:lang?", { lang: "en" });
+const defaultDocsPath = routePath("/docs/:lang?");
+```
+
+Static routes and routes with only optional parameters need no parameter object.
+An optional parameter can also be omitted from the params object; its URL
+segment is removed. Unknown route patterns and missing required or extra
+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.
 
 ### TypeScript setup
 

package/devtools/app.js

@@ -0,0 +1,143 @@
+const treeElement = document.querySelector("#tree");
+const statusElement = document.querySelector("#status");
+const errorElement = document.querySelector("#error");
+const filterElement = document.querySelector("#filter");
+const toggleElement = document.querySelector("#toggle");
+const fileLabels = {
+  page: "Page",
+  layout: "Layout",
+  loading: "Loading",
+  notFound: "Not found",
+  error: "Error boundary",
+};
+
+let manifest;
+let manifestSnapshot;
+let expanded = false;
+let expansionTouched = false;
+let refreshing = false;
+
+function createElement(tag, className, text) {
+  const element = document.createElement(tag);
+  if (className) element.className = className;
+  if (text !== undefined) element.textContent = text;
+  return element;
+}
+
+function renderNode(node, query, depth = 0) {
+  const children = node.children
+    .map((child) => renderNode(child, query, depth + 1))
+    .filter(Boolean);
+  const fileEntries = Object.entries(node.files ?? {});
+  const searchText = [
+    node.fullPath,
+    ...node.params,
+    ...fileEntries.flatMap(([kind, file]) => [kind, file]),
+  ]
+    .join(" ")
+    .toLowerCase();
+  const matches = !query || searchText.includes(query);
+  if (!matches && children.length === 0) return null;
+
+  const item = createElement("li", "route-node");
+  const details = createElement("details", "route-details");
+  details.open = query
+    ? true
+    : expansionTouched
+      ? expanded
+      : depth < 2;
+  const summary = createElement("summary", "route-summary");
+  const routePath = node.routeGroup
+    ? `${node.fullPath} (route group)`
+    : node.fullPath;
+  summary.append(createElement("code", "route-path", routePath));
+
+  if (node.routeGroup) {
+    summary.append(createElement("span", "badge group-badge", "group"));
+  }
+  for (const param of node.params) {
+    const optional = node.optionalParams?.includes(param);
+    summary.append(
+      createElement(
+        "span",
+        `badge ${optional ? "optional-badge" : "param-badge"}`,
+        optional ? `${param}?` : param,
+      ),
+    );
+  }
+  details.append(summary);
+
+  if (fileEntries.length) {
+    const files = createElement("ul", "file-list");
+    for (const [kind, file] of fileEntries) {
+      const row = createElement("li", "file-row");
+      row.append(
+        createElement("span", "file-kind", fileLabels[kind] ?? kind),
+        createElement("code", "file-path", file),
+      );
+      files.append(row);
+    }
+    details.append(files);
+  }
+
+  if (children.length) {
+    const childList = createElement("ul", "route-list");
+    childList.append(...children);
+    details.append(childList);
+  }
+  item.append(details);
+  return item;
+}
+
+function render() {
+  if (!manifest) return;
+  const query = filterElement.value.trim().toLowerCase();
+  const root = renderNode(manifest, query);
+  treeElement.replaceChildren();
+
+  if (!root) {
+    treeElement.append(createElement("p", "empty", "No routes match this filter."));
+  } else {
+    const list = createElement("ul", "route-list root-list");
+    list.append(root);
+    treeElement.append(list);
+  }
+  toggleElement.textContent = expanded ? "Collapse all" : "Expand all";
+  toggleElement.disabled = Boolean(query);
+}
+
+async function refresh() {
+  if (refreshing) return;
+  refreshing = true;
+  try {
+    const response = await fetch("/__vite-file-router-data", {
+      cache: "no-store",
+    });
+    if (!response.ok) throw new Error(`Request failed (${response.status})`);
+    const nextManifest = await response.json();
+    const nextSnapshot = JSON.stringify(nextManifest);
+    const manifestChanged = nextSnapshot !== manifestSnapshot;
+    manifest = nextManifest;
+    manifestSnapshot = nextSnapshot;
+    errorElement.hidden = true;
+    statusElement.textContent = "Route data refreshes automatically.";
+    if (manifestChanged) render();
+  } catch (error) {
+    errorElement.textContent = `Unable to load routes: ${error.message}`;
+    errorElement.hidden = false;
+    statusElement.textContent = "Route data is unavailable.";
+  } finally {
+    refreshing = false;
+  }
+}
+
+filterElement.addEventListener("input", render);
+document.querySelector("#refresh").addEventListener("click", refresh);
+toggleElement.addEventListener("click", () => {
+  expansionTouched = true;
+  expanded = !expanded;
+  render();
+});
+
+refresh();
+window.setInterval(refresh, 2000);

package/devtools/index.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Route Tree</title>
+    <link rel="stylesheet" href="/__vite-file-router/style.css" />
+  </head>
+  <body>
+    <main>
+      <header>
+        <div>
+          <p class="eyebrow">VITE FILE ROUTER</p>
+          <h1>Route tree</h1>
+          <p id="status" role="status">Loading routes...</p>
+        </div>
+        <button id="refresh" type="button" aria-label="Refresh routes">
+          Refresh
+        </button>
+      </header>
+      <section class="toolbar" aria-label="Route tree controls">
+        <label class="search">
+          <span class="visually-hidden">Filter routes</span>
+          <input id="filter" type="search" placeholder="Filter paths or files" />
+        </label>
+        <button id="toggle" type="button">Collapse all</button>
+      </section>
+      <p id="error" role="alert" hidden></p>
+      <div id="tree"></div>
+    </main>
+    <script type="module" src="/__vite-file-router/app.js"></script>
+  </body>
+</html>

package/devtools/style.css

@@ -0,0 +1,231 @@
+:root {
+  color-scheme: light dark;
+  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  font-size: 13px;
+  color: #24292f;
+  background: #fff;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+}
+
+main {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 24px;
+}
+
+header,
+.toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+header {
+  margin-bottom: 20px;
+}
+
+.eyebrow {
+  margin: 0 0 5px;
+  color: #6e7781;
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+}
+
+h1 {
+  margin: 0;
+  font-size: 22px;
+}
+
+#status {
+  margin: 6px 0 0;
+  color: #6e7781;
+}
+
+button,
+input {
+  min-height: 34px;
+  border: 1px solid #d0d7de;
+  border-radius: 6px;
+  background: #fff;
+  color: inherit;
+  font: inherit;
+}
+
+button {
+  padding: 0 12px;
+  cursor: pointer;
+}
+
+button:hover {
+  background: #f6f8fa;
+}
+
+.toolbar {
+  justify-content: flex-start;
+  margin-bottom: 16px;
+}
+
+.search {
+  flex: 1;
+}
+
+input {
+  width: 100%;
+  padding: 0 10px;
+}
+
+#error {
+  padding: 10px;
+  border: 1px solid #cf222e;
+  border-radius: 6px;
+  color: #cf222e;
+}
+
+.route-list,
+.file-list {
+  margin: 0;
+  padding-left: 20px;
+  list-style: none;
+}
+
+.root-list {
+  padding: 0;
+}
+
+.route-node {
+  position: relative;
+  padding: 3px 0;
+}
+
+.route-details {
+  min-width: 0;
+}
+
+.route-summary {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 7px;
+  min-height: 28px;
+  cursor: pointer;
+}
+
+.route-path,
+.file-path {
+  overflow-wrap: anywhere;
+  font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+}
+
+.route-path {
+  color: #0969da;
+  font-weight: 600;
+}
+
+.badge {
+  padding: 2px 6px;
+  border-radius: 10px;
+  background: #ddf4ff;
+  color: #0550ae;
+  font-size: 11px;
+}
+
+.group-badge {
+  background: #fbefff;
+  color: #8250df;
+}
+
+.optional-badge {
+  background: #fff8c5;
+  color: #7d4e00;
+}
+
+.file-list {
+  padding-top: 3px;
+  padding-bottom: 5px;
+}
+
+.file-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  padding: 3px 0;
+  color: #57606a;
+}
+
+.file-kind {
+  min-width: 90px;
+  font-weight: 600;
+}
+
+.empty {
+  padding: 20px 0;
+  color: #6e7781;
+}
+
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    color: #e6edf3;
+    background: #0d1117;
+  }
+
+  button,
+  input {
+    border-color: #30363d;
+    background: #161b22;
+  }
+
+  button:hover {
+    background: #21262d;
+  }
+
+  #error {
+    color: #ff7b72;
+  }
+
+  .route-path {
+    color: #79c0ff;
+  }
+
+  .badge {
+    background: #0c2d6b;
+    color: #a5d6ff;
+  }
+
+  .group-badge {
+    background: #2d1f4d;
+    color: #d2a8ff;
+  }
+
+  .optional-badge {
+    background: #3d2e00;
+    color: #eac54f;
+  }
+
+  .file-row,
+  .empty,
+  #status,
+  .eyebrow {
+    color: #8b949e;
+  }
+}

package/dist/index.js

@@ -1,4 +1,5 @@
 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";
@@ -12,8 +13,32 @@ var DEFAULT_CONVENTIONS = {
 };
 function getRouteSegment(name) {
 	if (name.startsWith("[...") && name.endsWith("]")) return "*";
+	const optionalParameter = /^\[\[(.+)\]\]$/.exec(name);
+	if (optionalParameter) return `:${optionalParameter[1]}?`;
 	return name.replace(/^\[(.+)\]$/, ":$1");
 }
+function getRouteParameter(name) {
+	if (name.startsWith("[...") && name.endsWith("]")) return {
+		name: "*",
+		optional: false
+	};
+	const optionalParameter = /^\[\[(.+)\]\]$/.exec(name);
+	if (optionalParameter) return {
+		name: optionalParameter[1],
+		optional: true
+	};
+	const parameter = /^\[(.+)\]$/.exec(name);
+	return parameter ? {
+		name: parameter[1],
+		optional: false
+	} : void 0;
+}
+function collectPageRoutePatterns(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;
+}
 function scan(directory, conventions = DEFAULT_CONVENTIONS) {
 	const node = {
 		name: path.basename(directory),
@@ -41,7 +66,9 @@ function scan(directory, conventions = DEFAULT_CONVENTIONS) {
 function createRouteManifest(node, projectRoot, parentPath = "", root = true) {
 	const segment = root || node.routeGroup ? null : getRouteSegment(node.name);
 	const fullPath = segment === null ? parentPath || "/" : `${parentPath}/${segment}` || "/";
-	const params = !root && !node.routeGroup && node.name.startsWith("[") ? [node.name.startsWith("[...") ? "*" : node.name.slice(1, -1)] : [];
+	const routeParameter = !root && !node.routeGroup ? getRouteParameter(node.name) : void 0;
+	const params = routeParameter ? [routeParameter.name] : [];
+	const optionalParams = routeParameter?.optional ? [routeParameter.name] : [];
 	const files = {};
 	for (const kind of Object.keys(DEFAULT_CONVENTIONS)) {
 		const file = node[kind];
@@ -51,6 +78,7 @@ function createRouteManifest(node, projectRoot, parentPath = "", root = true) {
 		segment,
 		fullPath,
 		params,
+		optionalParams,
 		routeGroup: node.routeGroup,
 		files,
 		children: node.children.map((child) => createRouteManifest(child, projectRoot, fullPath === "/" ? "" : fullPath, false))
@@ -61,7 +89,7 @@ var RouteConflictError = class extends Error {
 	conflicts;
 	constructor(conflicts) {
 		const details = conflicts.map(({ routePath, files }) => `  ${routePath}\n${files.map((file) => `    - ${file}`).join("\n")}`).join("\n");
-		super(`Multiple page files resolve to the same route pattern:\n${details}\n\nReact Router treats dynamic parameters as equivalent regardless of their names, and parenthesized route-group names are omitted from URLs. Give each page a unique URL pattern.`);
+		super(`Multiple page files resolve to the same route pattern:\n${details}\n\nReact Router treats dynamic parameters as equivalent regardless of their names, and parenthesized route-group names are omitted from URLs. Optional segments also match URLs without that segment. Give each page a unique URL pattern.`);
 		this.conflicts = conflicts;
 		this.name = "RouteConflictError";
 	}
@@ -76,8 +104,12 @@ function getRoutePath(directory) {
 function findPageRouteConflicts(node, pages = /* @__PURE__ */ new Map(), segments = [], root = true) {
 	const routeSegments = root || node.routeGroup ? segments : [...segments, getRoutePath(node.directory)];
 	if (node.page) {
-		const routePath = `/${routeSegments.map((segment) => segment.startsWith(":") ? ":" : segment).join("/")}`;
-		pages.set(routePath, [...pages.get(routePath) ?? [], node.page]);
+		const variants = routeSegments.reduce((paths, segment) => segment.startsWith(":") && segment.endsWith("?") ? paths.flatMap((segments) => [[...segments, segment.slice(0, -1)], segments]) : paths.map((segments) => [...segments, segment]), [[]]);
+		for (const variant of variants) {
+			const routePath = `/${variant.map((segment) => segment.startsWith(":") ? ":" : segment).join("/")}`;
+			const files = pages.get(routePath) ?? [];
+			if (!files.includes(node.page)) pages.set(routePath, [...files, node.page]);
+		}
 	}
 	for (const child of node.children) findPageRouteConflicts(child, pages, routeSegments, false);
 	return [...pages.entries()].filter(([, files]) => files.length > 1).map(([routePath, files]) => ({
@@ -210,6 +242,10 @@ var ROUTES_MODULE_ID = "virtual:routes";
 var ROUTES_RESOLVED_ID = `\0${ROUTES_MODULE_ID}`;
 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";
 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.");
@@ -281,6 +317,72 @@ function routes(input = "src/pages") {
 		const manifest = createRouteManifest(scan(root, options.conventions), projectRoot);
 		return format(`export const routeManifest = ${JSON.stringify(manifest, null, 2)};`, { parser: "typescript" });
 	}
+	async function executeRouteHelpers() {
+		const tree = scan(root, options.conventions);
+		const patterns = [...new Set(collectPageRoutePatterns(tree))].sort();
+		const code = `
+      export const routePatterns = ${JSON.stringify(patterns)};
+
+      export function routePath(pattern, ...args) {
+        if (!routePatterns.includes(pattern)) {
+          throw new TypeError(\`Unknown route pattern "\${pattern}".\`);
+        }
+
+        const params = args[0] ?? {};
+        const segments = pattern.split("/").slice(1);
+        const parameterNames = segments.flatMap((segment) => {
+          const parameter = /^:([^/?]+)(\\?)?$/.exec(segment);
+          return parameter ? [parameter[1]] : segment === "*" ? ["*"] : [];
+        });
+        for (const key of Object.keys(params)) {
+          if (!parameterNames.includes(key)) {
+            throw new TypeError(\`Unknown route parameter "\${key}" for "\${pattern}".\`);
+          }
+        }
+        let omittedOptionalParameter = false;
+        const pathSegments = segments.map((segment) => {
+          const parameter = /^:([^/?]+)(\\?)?$/.exec(segment);
+          const key = parameter?.[1] ?? (segment === "*" ? "*" : undefined);
+          if (key === undefined) return segment;
+          const optional = parameter?.[2] === "?";
+          if (!Object.hasOwn(params, key)) {
+            if (optional) {
+              omittedOptionalParameter = true;
+              return undefined;
+            }
+            throw new TypeError(\`Missing route parameter "\${key}" for "\${pattern}".\`);
+          }
+          if (optional && params[key] === undefined) {
+            omittedOptionalParameter = true;
+            return undefined;
+          }
+          if (omittedOptionalParameter) {
+            throw new TypeError(
+              \`Cannot provide route parameter "\${key}" for "\${pattern}" when an earlier optional parameter is omitted.\`,
+            );
+          }
+          const value = String(params[key]);
+          if (key !== "*" && value.length === 0) {
+            throw new TypeError(
+              'Route parameter "' +
+                key +
+                '" for "' +
+                pattern +
+                '" cannot be empty.',
+            );
+          }
+          const encoded = key === "*"
+            ? value.split("/").map(encodeURIComponent).join("/")
+            : encodeURIComponent(value);
+          return encoded;
+        });
+        return \`/\${pathSegments
+          .filter((segment) => segment !== undefined)
+          .join("/")}\`;
+      }
+    `;
+		return format(code, { parser: "typescript" });
+	}
 	return {
 		name: "routes",
 		configResolved(config) {
@@ -291,11 +393,41 @@ function routes(input = "src/pages") {
 		resolveId: (id) => {
 			if (id === ROUTES_MODULE_ID) return ROUTES_RESOLVED_ID;
 			if (id === MANIFEST_MODULE_ID) return MANIFEST_RESOLVED_ID;
+			if (id === ROUTE_HELPERS_MODULE_ID) return ROUTE_HELPERS_RESOLVED_ID;
 		},
 		load: (id) => {
 			if (id === ROUTES_RESOLVED_ID) return execute();
 			if (id === MANIFEST_RESOLVED_ID) return executeManifest();
+			if (id === ROUTE_HELPERS_RESOLVED_ID) return executeRouteHelpers();
 		},
+		devtools: { setup(ctx) {
+			if (ctx.mode !== "dev" || !ctx.viteServer) return;
+			ctx.views.hostStatic(ROUTE_INSPECTOR_PATH, fileURLToPath(new URL("../devtools/", import.meta.url)));
+			ctx.docks.register({
+				id: "vite-file-router:routes",
+				title: "Routes",
+				icon: "ph:tree-structure-duotone",
+				type: "iframe",
+				url: ROUTE_INSPECTOR_PATH
+			});
+			ctx.viteServer.middlewares.use((req, res, next) => {
+				if (new URL(req.url ?? "/", "http://vite-file-router").pathname !== ROUTE_INSPECTOR_DATA_PATH) {
+					next();
+					return;
+				}
+				if (req.method !== "GET") {
+					res.statusCode = 405;
+					res.setHeader("Allow", "GET");
+					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));
+			});
+		} },
 		configureServer: (server) => {
 			server.watcher.add(root);
 			server.watcher.on("all", (event, file) => {
@@ -309,7 +441,11 @@ function routes(input = "src/pages") {
 				const location = path.resolve(file);
 				const relative = path.relative(root, location);
 				if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return;
-				for (const id of [ROUTES_RESOLVED_ID, MANIFEST_RESOLVED_ID]) {
+				for (const id of [
+					ROUTES_RESOLVED_ID,
+					MANIFEST_RESOLVED_ID,
+					ROUTE_HELPERS_RESOLVED_ID
+				]) {
 					const module = server.moduleGraph.getModuleById(id);
 					if (module) server.moduleGraph.invalidateModule(module);
 				}

package/dist/scanner.d.ts

@@ -15,11 +15,13 @@ export type RouteManifestNode = {
     segment: string | null;
     fullPath: string;
     params: string[];
+    optionalParams: string[];
     routeGroup: boolean;
     files: Partial<Record<RouteFileKind, string>>;
     children: 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 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.2.6",
+  "version": "0.2.8",
   "description": "File-system routing plugin for Vite",
   "type": "module",
   "private": false,
@@ -16,7 +16,8 @@
   },
   "files": [
     "dist",
-    "types"
+    "types",
+    "devtools"
   ],
   "main": "./dist/index.js",
   "types": "./types/index.d.ts",
@@ -37,6 +38,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.6.4",
+    "@vitejs/devtools-kit": "^0.8.2",
     "@types/node": "^24.19.2",
     "typescript": "~6.0.3",
     "vite": "^8.3.5"

package/types/index.d.ts

@@ -7,3 +7,54 @@ export type {
   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>]
+    : [];

package/types/virtual-routes.d.ts

@@ -7,3 +7,13 @@ 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;
+}