@troyio/vite-file-router 0.2.5 → 0.2.7

package/README.md

@@ -21,13 +21,36 @@ export default defineConfig({
 });
 ```
 
-By default, the plugin scans `src/pages`. Pass a path relative to the Vite
-project root to use another directory:
+By default, the plugin scans `src/pages` and recognizes the file conventions
+listed below. Pass a path relative to the Vite project root to use another
+directory:
 
 ```ts
 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:
+
+```ts
+plugins: [
+  routes({
+    directory: "app/views",
+    conventions: {
+      page: "route",
+      layout: "shell",
+      loading: "pending",
+      notFound: "missing",
+      error: "fault",
+    },
+  }),
+];
+```
+
+Omitted convention values keep their defaults: `page`, `layout`, `loading`,
+`not-found`, and `error`. 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:
 
@@ -135,7 +158,11 @@ Two pages must not resolve to the same URL. This includes pages with the same
 path in separate route groups, such as `(auth)/sign-in/page.tsx` and
 `(guest)/sign-in/page.tsx`. During development, the router displays a diagnostic
 page listing the conflicting files; production builds fail with the same
-diagnostic until the conflict is fixed.
+diagnostic until the conflict is fixed. Dynamic parameter names do not make
+otherwise identical patterns distinct (`users/[id]` and `users/[slug]`
+conflict). Static and dynamic siblings such as `users/new` and `users/[id]`
+are distinct; React Router's normal route ranking selects the static route
+first.
 
 ## Use the generated routes
 
@@ -152,6 +179,55 @@ export default function App() {
 }
 ```
 
+### Route manifest
+
+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:
+
+```ts
+import { routeManifest } from "virtual:route-manifest";
+
+console.log(routeManifest.children);
+```
+
+The root node has `fullPath: "/"`; route-group nodes have no URL segment but
+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 all generated virtual modules and
+reloads the app without requiring a server restart.
+
+### 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" });
+```
+
+Static routes need no parameter object: `routePath("/")`. Unknown route
+patterns and missing or extra parameters are rejected at runtime. The generated
+`routePatterns` export contains the discovered page paths.
+
 ### TypeScript setup
 
 Add Vite's client types and the package's virtual-module declaration to your

package/dist/generator.d.ts

@@ -1,4 +1,4 @@
-import type { Node } from "./scanner";
+import { type Node } from "./scanner";
 export type GeneratedRoutes = {
     imports: string[];
     helpers: string[];

package/dist/index.d.ts

@@ -1,2 +1,8 @@
 import type { Plugin } from "vite";
-export declare function routes(directory?: string): Plugin;
+import { type RouteConventions } from "./scanner";
+export type RoutesOptions = {
+    directory?: string;
+    conventions?: RouteConventions;
+};
+export type { RouteConventions, RouteFileKind, RouteManifestNode, } from "./scanner";
+export declare function routes(input?: string | RoutesOptions): Plugin;

package/dist/index.js

@@ -2,12 +2,72 @@ import path from "node:path";
 import { genArrayFromRaw, genObjectFromRaw, genSafeVariableName } from "knitwork";
 import { format } from "prettier";
 import fs from "node:fs";
+// src/scanner.ts
+var DEFAULT_CONVENTIONS = {
+	page: "page",
+	layout: "layout",
+	loading: "loading",
+	notFound: "not-found",
+	error: "error"
+};
+function getRouteSegment(name) {
+	if (name.startsWith("[...") && name.endsWith("]")) return "*";
+	return name.replace(/^\[(.+)\]$/, ":$1");
+}
+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),
+		directory,
+		routeGroup: /^\(.+\)$/.test(path.basename(directory)),
+		children: []
+	};
+	if (!fs.existsSync(directory)) return node;
+	const entries = fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+	for (const entry of entries) {
+		const file = path.join(directory, entry.name);
+		if (entry.isDirectory()) {
+			node.children.push(scan(file, conventions));
+			continue;
+		}
+		const match = /^(.*)\.(jsx|tsx)$/.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;
+	}
+	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 files = {};
+	for (const kind of Object.keys(DEFAULT_CONVENTIONS)) {
+		const file = node[kind];
+		if (file) files[kind] = path.relative(projectRoot, file).split(path.sep).join("/");
+	}
+	return {
+		segment,
+		fullPath,
+		params,
+		routeGroup: node.routeGroup,
+		files,
+		children: node.children.map((child) => createRouteManifest(child, projectRoot, fullPath === "/" ? "" : fullPath, false))
+	};
+}
 // src/generator.ts
 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:\n${details}\n\nGive each page a unique URL path. Parenthesized route-group names are omitted from URLs, so pages in different groups can still conflict.`);
+		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.`);
 		this.conflicts = conflicts;
 		this.name = "RouteConflictError";
 	}
@@ -17,9 +77,7 @@ function getImportPath(file, projectRoot) {
 	return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
 }
 function getRoutePath(directory) {
-	const segment = path.basename(directory);
-	if (segment.startsWith("[...") && segment.endsWith("]")) return "*";
-	return segment.replace(/^\[(.+)\]$/, ":$1");
+	return getRouteSegment(path.basename(directory));
 }
 function findPageRouteConflicts(node, pages = /* @__PURE__ */ new Map(), segments = [], root = true) {
 	const routeSegments = root || node.routeGroup ? segments : [...segments, getRoutePath(node.directory)];
@@ -153,34 +211,35 @@ function generate(node, root = false, projectRoot = process.cwd()) {
 		routes
 	};
 }
-// src/scanner.ts
-function scan(directory) {
-	const node = {
-		name: path.basename(directory),
+// src/index.ts
+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}`;
+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}".`);
+	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 };
+	if (options.conventions !== void 0 && (!options.conventions || typeof options.conventions !== "object" || Array.isArray(options.conventions))) throw new TypeError("routes() conventions must be an object.");
+	for (const [kind, basename] of Object.entries(options.conventions ?? {})) {
+		if (!Object.hasOwn(DEFAULT_CONVENTIONS, kind)) throw new TypeError(`Unknown route file convention "${kind}".`);
+		if (typeof basename !== "string" || basename.trim() === "" || basename === "." || basename === ".." || /[\\/]/.test(basename) || /\.[^.]+$/.test(basename)) throw new TypeError(`Route file convention "${kind}" must be a filename without an extension.`);
+		conventions[kind] = basename;
+	}
+	const names = Object.values(conventions);
+	if (new Set(names).size !== names.length) throw new TypeError("Route file convention names must be unique.");
+	return {
 		directory,
-		routeGroup: /^\(.+\)$/.test(path.basename(directory)),
-		children: []
+		conventions
 	};
-	if (!fs.existsSync(directory)) return node;
-	const entries = fs.readdirSync(directory, { withFileTypes: true });
-	for (const entry of entries) {
-		const file = path.join(directory, entry.name);
-		if (entry.isDirectory()) {
-			node.children.push(scan(file));
-			continue;
-		}
-		const match = /^(page|layout|loading|not-found|error)\.(jsx|tsx)$/.exec(entry.name);
-		if (!match) continue;
-		const [, name, extension] = match;
-		const key = name === "not-found" ? "notFound" : name;
-		if (!node[key] || extension === "tsx") node[key] = file;
-	}
-	return node;
 }
-// src/index.ts
-var MODULE_ID = "virtual:routes";
-var RESOLVED_ID = `\0${MODULE_ID}`;
-function routes(directory = "src/pages") {
+function routes(input = "src/pages") {
+	const options = resolveOptions(input);
 	let projectRoot = "";
 	let root = "";
 	let dev = false;
@@ -194,7 +253,7 @@ function routes(directory = "src/pages") {
 		});
 	}
 	async function execute() {
-		const tree = scan(root);
+		const tree = scan(root, options.conventions);
 		const conflicts = findPageRouteConflicts(tree);
 		if (conflicts.length) {
 			const error = new RouteConflictError(conflicts);
@@ -209,7 +268,7 @@ function routes(directory = "src/pages") {
             "main",
             { style: { fontFamily: "system-ui, sans-serif", margin: "3rem auto", maxWidth: "60rem", padding: "0 1.5rem" } },
             createElement("h1", null, "Conflicting routes"),
-            createElement("p", null, "The file-based router found page files that resolve to the same URL. Fix these conflicts, then the page will reload."),
+            createElement("p", null, "The file-based router found pages with the same effective URL pattern. React Router treats dynamic parameter names as equivalent, and route-group names do not add URL segments. Fix these conflicts, then the page will reload."),
             createElement("pre", { style: { background: "#f3f4f6", overflowX: "auto", padding: "1rem", whiteSpace: "pre-wrap" } }, message),
           );
         }
@@ -226,15 +285,70 @@ function routes(directory = "src/pages") {
 		].filter(Boolean);
 		return format(sections.join("\n\n"), { parser: "typescript" });
 	}
+	async function executeManifest() {
+		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 parameterNames = [...pattern.matchAll(/:([^/]+)|\\*/g)].map(
+          ([, name]) => name ?? "*",
+        );
+        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 ?? "*";
+          if (!Object.hasOwn(params, key)) {
+            throw new TypeError(\`Missing route parameter "\${key}" for "\${pattern}".\`);
+          }
+          const value = String(params[key]);
+          if (key !== "*" && value.length === 0) {
+            throw new TypeError(
+              'Route parameter "' +
+                key +
+                '" for "' +
+                pattern +
+                '" cannot be empty.',
+            );
+          }
+          return key === "*"
+            ? value.split("/").map(encodeURIComponent).join("/")
+            : encodeURIComponent(value);
+        });
+      }
+    `;
+		return format(code, { parser: "typescript" });
+	}
 	return {
 		name: "routes",
 		configResolved(config) {
 			projectRoot = config.root;
-			root = path.resolve(projectRoot, directory);
+			root = path.resolve(projectRoot, options.directory);
 			dev = config.command === "serve";
 		},
-		resolveId: (id) => id === MODULE_ID ? RESOLVED_ID : void 0,
-		load: (id) => id === RESOLVED_ID ? execute() : void 0,
+		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();
+		},
 		configureServer: (server) => {
 			server.watcher.add(root);
 			server.watcher.on("all", (event, file) => {
@@ -246,9 +360,16 @@ function routes(directory = "src/pages") {
 					"change"
 				].includes(event)) return;
 				const location = path.resolve(file);
-				if (location !== root && !location.startsWith(root + path.sep)) return;
-				const module = server.moduleGraph.getModuleById(RESOLVED_ID);
-				if (module) server.moduleGraph.invalidateModule(module);
+				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,
+					ROUTE_HELPERS_RESOLVED_ID
+				]) {
+					const module = server.moduleGraph.getModuleById(id);
+					if (module) server.moduleGraph.invalidateModule(module);
+				}
 				server.ws.send({ type: "full-reload" });
 			});
 		}

package/dist/scanner.d.ts

@@ -9,4 +9,18 @@ export type Node = {
     error?: string;
     children: Node[];
 };
-export declare function scan(directory: string): Node;
+export type RouteFileKind = "page" | "layout" | "loading" | "notFound" | "error";
+export type RouteConventions = Partial<Record<RouteFileKind, string>>;
+export type RouteManifestNode = {
+    segment: string | null;
+    fullPath: string;
+    params: 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.5",
+  "version": "0.2.7",
   "description": "File-system routing plugin for Vite",
   "type": "module",
   "private": false,

package/types/index.d.ts

@@ -1,3 +1,53 @@
 /// <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 "*"
+      ? { "*": 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 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]
+      : [params: RouteParameters<Path>]
+    : [];

package/types/virtual-routes.d.ts

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