@troyio/vite-file-router 0.2.7 → 0.3.0

package/README.md

@@ -29,9 +29,10 @@ directory:
 plugins: [routes("src/routes")];
 ```
 
-You can also configure the directory and special filenames together. Convention
-values are filename stems without `.jsx` or `.tsx`; `.tsx` takes precedence when
-both extensions exist:
+You can also configure the directory and special filenames together.
+Convention values are filename stems without extensions. Page and component
+conventions use `.jsx` / `.tsx` files (`.tsx` takes precedence); `loader` and
+`action` conventions use `.js` / `.ts` files (`.ts` takes precedence):
 
 ```ts
 plugins: [
@@ -43,13 +44,16 @@ plugins: [
       loading: "pending",
       notFound: "missing",
       error: "fault",
+      loader: "load",
+      action: "mutate",
     },
   }),
 ];
 ```
 
 Omitted convention values keep their defaults: `page`, `layout`, `loading`,
-`not-found`, and `error`. Each convention must have a unique filename stem.
+`not-found`, `error`, `loader`, and `action`. Each convention must have a
+unique filename stem.
 
 The router scans the pages directory recursively. Each directory becomes a
 nested route, and the following files are recognized:
@@ -61,9 +65,13 @@ nested route, and the following files are recognized:
 | `loading.jsx` / `loading.tsx` | A Suspense fallback for the directory's page and child routes. |
 | `not-found.jsx` / `not-found.tsx` | A not-found page for unmatched URLs within the directory's route subtree. |
 | `error.jsx` / `error.tsx` | A React Router error boundary for the directory's route subtree. |
+| `loader.js` / `loader.ts` | A React Router loader for the directory's route and its descendants. |
+| `action.js` / `action.ts` | A React Router action selected when that directory route is the submission target. |
 
-Each file must default-export a React component. If both extensions exist for
-the same file type in one directory, `.tsx` takes precedence.
+Component files must default-export a React component. Loader and action
+modules must named-export their handler as `loader` or `action`; if both
+supported extensions exist for the same convention in one directory, the
+TypeScript file takes precedence.
 
 For example, this structure creates a home page, user pages, and two auth
 pages:
@@ -73,10 +81,15 @@ src/pages/
   page.jsx
   layout.tsx
   loading.tsx
+  loader.ts
   users/
     page.tsx
+    action.ts
     [id]/
       page.tsx
+  docs/
+    [[lang]]/
+      page.tsx
   (auth)/
     layout.tsx
     sign-in/
@@ -87,11 +100,13 @@ 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.
+are route groups; they organize files and can have their own page, layout,
+loading files, loaders, and actions, but their names do not add a URL segment.
 
 ### Layouts
 
@@ -152,6 +167,70 @@ export default function ErrorPage() {
 }
 ```
 
+### Loaders, actions, and route guards
+
+Add a `loader.ts` / `loader.js` or `action.ts` / `action.js` beside the route
+files and export a named handler. The generated React Router route calls these
+handlers with React Router's loader/action arguments. Their returned values,
+thrown errors, and redirect responses use React Router's normal data-router
+behavior. A loader on a directory route runs when that route matches, including
+when a descendant URL matches. An action runs only when its route is selected
+as the submission target; a parent action does not automatically handle
+submissions targeting child routes.
+
+Use a loader to redirect users who should not enter a protected route subtree.
+For example, `src/pages/dashboard/loader.ts` can guard `/dashboard` and all of
+its nested pages:
+
+```ts
+import { redirect, type LoaderFunctionArgs } from "react-router";
+import { getUserForRequest } from "../../lib/auth.server";
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  const user = await getUserForRequest(request);
+  if (!user) {
+    const returnTo = new URL(request.url).pathname;
+    throw redirect(`/sign-in?returnTo=${encodeURIComponent(returnTo)}`);
+  }
+  return null;
+}
+```
+
+Actions use the same pattern and receive React Router's `ActionFunctionArgs`:
+
+```ts
+import { redirect, type ActionFunctionArgs } from "react-router";
+
+export async function action({ request }: ActionFunctionArgs) {
+  const formData = await request.formData();
+  await updateProfile(formData);
+  return redirect("/profile");
+}
+```
+
+When a directory has both a page and a loader, that page is generated as an
+index child route, while the loader remains on the directory route so it also
+runs for descendant pages. Read the directory loader's result in the page with
+React Router's `useRouteLoaderData`. The generated route ID is
+`file-route:` followed by the directory path relative to the Vite project
+root, with `/` separators:
+
+```tsx
+import { useRouteLoaderData } from "react-router";
+
+export default function DashboardPage() {
+  const data = useRouteLoaderData<{ message: string }>(
+    "file-route:src/pages/dashboard",
+  );
+  return <h1>{data?.message}</h1>;
+}
+```
+
+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,
+and do not rely on a parent loader running before descendant loaders.
+
 ### Dynamic routes and route groups
 
 Two pages must not resolve to the same URL. This includes pages with the same
@@ -169,7 +248,8 @@ first.
 Import `routes` from the virtual module and pass it to React Router:
 
 ```tsx
-import { createBrowserRouter, RouterProvider } from "react-router";
+import { createBrowserRouter } from "react-router";
+import { RouterProvider } from "react-router";
 import { routes } from "virtual:routes";
 
 const router = createBrowserRouter(routes);
@@ -184,7 +264,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";
@@ -200,6 +281,29 @@ The development server watches the configured directory. Adding, removing,
 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
@@ -222,10 +326,15 @@ export function UserLink({ userId }: { userId: string }) {
 }
 
 const docsPath = routePath("/docs/*", { "*": "guides/getting-started" });
+const localizedDocsPath = routePath("/docs/:lang?", { lang: "en" });
+const defaultDocsPath = routePath("/docs/:lang?");
 ```
 
-Static routes need no parameter object: `routePath("/")`. Unknown route
-patterns and missing or extra parameters are rejected at runtime. The generated
+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";
@@ -8,12 +9,32 @@ var DEFAULT_CONVENTIONS = {
 	layout: "layout",
 	loading: "loading",
 	notFound: "not-found",
-	error: "error"
+	error: "error",
+	loader: "loader",
+	action: "action"
 };
 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("/")}`] : [];
@@ -35,19 +56,24 @@ function scan(directory, conventions = DEFAULT_CONVENTIONS) {
 			node.children.push(scan(file, conventions));
 			continue;
 		}
-		const match = /^(.*)\.(jsx|tsx)$/.exec(entry.name);
+		const match = /^(.*)\.(jsx|tsx|js|ts)$/.exec(entry.name);
 		if (!match) continue;
 		const [, basename, extension] = match;
 		const kind = Object.keys(conventions).find((candidate) => conventions[candidate] === basename);
 		if (!kind) continue;
-		if (!node[kind] || extension === "tsx") node[kind] = file;
+		const isDataModule = kind === "loader" || kind === "action";
+		if (!(isDataModule ? ["js", "ts"] : ["jsx", "tsx"]).includes(extension)) continue;
+		const preferredExtension = isDataModule ? "ts" : "tsx";
+		if (!node[kind] || extension === preferredExtension) node[kind] = file;
 	}
 	return node;
 }
 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];
@@ -57,6 +83,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))
@@ -67,7 +94,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";
 	}
@@ -82,8 +109,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]) => ({
@@ -112,15 +143,24 @@ 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, kind, projectRoot) {
+	return `async (args) => (await import(${JSON.stringify(getImportPath(file, projectRoot))})).${kind}(args)`;
+}
+function getRouteId(directory, projectRoot) {
+	return `file-route:${path.relative(projectRoot, directory).split(path.sep).join("/") || "."}`;
+}
 function generateNode(node, root, context, inheritedBoundary) {
 	const route = {};
 	const hasBoundary = inheritedBoundary || Boolean(node.loading);
 	if (node.layout) context.hasLayouts = true;
 	if (!root && !node.routeGroup) route.path = JSON.stringify(getRoutePath(node.directory));
+	if (node.loader) route.id = JSON.stringify(getRouteId(node.directory, context.projectRoot));
 	if (node.error) {
 		context.hasErrorBoundaries = true;
 		route.ErrorBoundary = `createErrorBoundary(${generateLazyComponent(node.error, context.projectRoot)})`;
 	}
+	if (node.loader) route.loader = generateDataHandler(node.loader, "loader", context.projectRoot);
+	if (node.action) route.action = generateDataHandler(node.action, "action", context.projectRoot);
 	let loadingComponent;
 	if (node.loading) {
 		loadingComponent = genSafeVariableName(`Loading${context.nextLoadingId++}`);
@@ -138,10 +178,12 @@ function generateNode(node, root, context, inheritedBoundary) {
 	if (node.page) {
 		const page = hasBoundary ? {
 			index: "true",
-			Component: generateLazyComponent(node.page, context.projectRoot)
+			Component: generateLazyComponent(node.page, context.projectRoot),
+			...node.action ? { action: generateDataHandler(node.action, "action", context.projectRoot) } : {}
 		} : {
 			index: "true",
-			lazy: generateImport(node.page, context.projectRoot)
+			lazy: generateImport(node.page, context.projectRoot),
+			...node.action ? { action: generateDataHandler(node.action, "action", context.projectRoot) } : {}
 		};
 		children.push(genObjectFromRaw(page));
 	}
@@ -218,6 +260,8 @@ 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.");
@@ -301,19 +345,38 @@ function routes(input = "src/pages") {
         }
 
         const params = args[0] ?? {};
-        const parameterNames = [...pattern.matchAll(/:([^/]+)|\\*/g)].map(
-          ([, name]) => name ?? "*",
-        );
+        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}".\`);
           }
         }
-        return pattern.replace(/:([^/]+)|\\*/g, (token, name) => {
-          const key = name ?? "*";
+        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(
@@ -324,10 +387,14 @@ function routes(input = "src/pages") {
                 '" cannot be empty.',
             );
           }
-          return key === "*"
+          const encoded = key === "*"
             ? value.split("/").map(encodeURIComponent).join("/")
             : encodeURIComponent(value);
+          return encoded;
         });
+        return \`/\${pathSegments
+          .filter((segment) => segment !== undefined)
+          .join("/")}\`;
       }
     `;
 		return format(code, { parser: "typescript" });
@@ -349,6 +416,34 @@ function routes(input = "src/pages") {
 			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) => {

package/dist/scanner.d.ts

@@ -7,14 +7,17 @@ export type Node = {
     loading?: string;
     notFound?: string;
     error?: string;
+    loader?: string;
+    action?: string;
     children: Node[];
 };
-export type RouteFileKind = "page" | "layout" | "loading" | "notFound" | "error";
+export type RouteFileKind = "page" | "layout" | "loading" | "notFound" | "error" | "loader" | "action";
 export type RouteConventions = Partial<Record<RouteFileKind, string>>;
 export type RouteManifestNode = {
     segment: string | null;
     fullPath: string;
     params: string[];
+    optionalParams: string[];
     routeGroup: boolean;
     files: Partial<Record<RouteFileKind, string>>;
     children: RouteManifestNode[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@troyio/vite-file-router",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "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",
@@ -38,6 +39,9 @@
   "devDependencies": {
     "@biomejs/biome": "^2.6.4",
     "@types/node": "^24.19.2",
+    "@vitejs/devtools-kit": "^0.8.2",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
     "typescript": "~6.0.3",
     "vite": "^8.3.5"
   },

package/types/index.d.ts

@@ -11,7 +11,9 @@ export type {
 export type RouteParameterValue = string | number;
 
 type RouteParametersForSegment<Segment extends string> =
-  Segment extends `:${infer Name}`
+  Segment extends `:${infer Name}?`
+    ? { [Key in Name]?: RouteParameterValue }
+    : Segment extends `:${infer Name}`
     ? { [Key in Name]: RouteParameterValue }
     : Segment extends "*"
       ? { "*": RouteParameterValue }
@@ -38,6 +40,9 @@ type RouteRequiresParameters<Path extends string> =
       : 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>>,
@@ -49,5 +54,7 @@ export type RoutePathArguments<Path extends string> =
   true extends RouteRequiresParameters<Path>
     ? HasParameterShapeMismatch<Path> extends true
       ? [params: never]
-      : [params: RouteParameters<Path>]
+      : true extends RouteRequiresRequiredParameters<Path>
+        ? [params: RouteParameters<Path>]
+        : [params?: RouteParameters<Path>]
     : [];