@troyio/vite-file-router 0.2.4 → 0.2.6

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:
 
@@ -36,6 +59,8 @@ nested route, and the following files are recognized:
 | `page.jsx` / `page.tsx` | The page component for the directory's URL. |
 | `layout.jsx` / `layout.tsx` | A layout around the directory's page and child routes. |
 | `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. |
 
 Each file must default-export a React component. If both extensions exist for
 the same file type in one directory, `.tsx` takes precedence.
@@ -95,13 +120,49 @@ export default function Loading() {
 
 A nested loading file creates a more specific boundary for that directory.
 
+### Not-found pages
+
+Add a `not-found.jsx` or `not-found.tsx` file to handle unmatched URLs. The plugin generates
+a catch-all child route, and the most specific matching route subtree's
+not-found page is used:
+
+```text
+src/pages/
+  not-found.tsx
+  users/
+    not-found.tsx
+    page.tsx
+```
+
+The root not-found page handles unknown URLs generally, while `users/not-found.tsx`
+handles unmatched URLs under `/users`.
+
+### Route error boundaries
+
+Add an `error.jsx` or `error.tsx` file to handle errors from that route and its
+descendants. The nearest route boundary is used, following React Router's error
+handling behavior. Use React Router's `useRouteError` hook to read the error:
+
+```tsx
+import { useRouteError } from "react-router";
+
+export default function ErrorPage() {
+  const error = useRouteError();
+  return <main>Something went wrong: {String(error)}</main>;
+}
+```
+
 ### Dynamic routes and route groups
 
 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
 
@@ -118,6 +179,27 @@ 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 both virtual modules and reloads
+the app without requiring a server restart.
+
 ### 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,66 @@ 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 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 +71,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)];
@@ -33,15 +85,20 @@ function findPageRouteConflicts(node, pages = /* @__PURE__ */ new Map(), segment
 		files
 	}));
 }
+function validateRouteGroupNotFound(node, segments = [], root = true) {
+	const routeSegments = root || node.routeGroup ? segments : [...segments, getRoutePath(node.directory)];
+	if (node.routeGroup && node.notFound && routeSegments.length === 0) throw new Error(`Route-group not-found page "${node.notFound}" has no URL subtree to match. Move it into a directory with a URL segment so it is scoped to a distinct route subtree.`);
+	for (const child of node.children) validateRouteGroupNotFound(child, routeSegments, false);
+}
 function generateImport(file, projectRoot) {
 	return `async () => ({
     Component: (await import(${JSON.stringify(getImportPath(file, projectRoot))})).default
   })`;
 }
-function generateLayoutImport(file, projectRoot) {
-	return `async () => ({
-    Component: withOutlet((await import(${JSON.stringify(getImportPath(file, projectRoot))})).default)
-  })`;
+function generateRouteLazy(node, projectRoot, includeLayout) {
+	const properties = [];
+	if (includeLayout && node.layout) properties.push(`Component: withOutlet((await import(${JSON.stringify(getImportPath(node.layout, projectRoot))})).default)`);
+	return `async () => ({ ${properties.join(", ")} })`;
 }
 function generateLazyComponent(file, projectRoot) {
 	return `lazy(() => import(${JSON.stringify(getImportPath(file, projectRoot))}))`;
@@ -54,6 +111,10 @@ function generateNode(node, root, context, inheritedBoundary) {
 	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.error) {
+		context.hasErrorBoundaries = true;
+		route.ErrorBoundary = `createErrorBoundary(${generateLazyComponent(node.error, context.projectRoot)})`;
+	}
 	let loadingComponent;
 	if (node.loading) {
 		loadingComponent = genSafeVariableName(`Loading${context.nextLoadingId++}`);
@@ -65,8 +126,8 @@ function generateNode(node, root, context, inheritedBoundary) {
 		route.Component = `createBoundary(${loadingComponent}, ${child})`;
 	} else if (node.layout) {
 		if (hasBoundary) route.Component = generateLazyLayout(node.layout, context.projectRoot);
-		else route.lazy = generateLayoutImport(node.layout, context.projectRoot);
 	}
+	if (node.layout && !hasBoundary) route.lazy = generateRouteLazy(node, context.projectRoot, true);
 	const children = [];
 	if (node.page) {
 		const page = hasBoundary ? {
@@ -79,10 +140,21 @@ function generateNode(node, root, context, inheritedBoundary) {
 		children.push(genObjectFromRaw(page));
 	}
 	for (const child of node.children) children.push(generateNode(child, false, context, hasBoundary));
+	if (node.notFound) {
+		const notFoundRoute = hasBoundary ? {
+			path: JSON.stringify("*"),
+			Component: generateLazyComponent(node.notFound, context.projectRoot)
+		} : {
+			path: JSON.stringify("*"),
+			lazy: generateImport(node.notFound, context.projectRoot)
+		};
+		children.push(genObjectFromRaw(notFoundRoute));
+	}
 	if (children.length) route.children = genArrayFromRaw(children);
 	return genObjectFromRaw(route);
 }
 function generate(node, root = false, projectRoot = process.cwd()) {
+	validateRouteGroupNotFound(node, [], root);
 	const conflicts = findPageRouteConflicts(node, /* @__PURE__ */ new Map(), [], root);
 	if (conflicts.length) throw new RouteConflictError(conflicts);
 	const context = {
@@ -90,15 +162,17 @@ function generate(node, root = false, projectRoot = process.cwd()) {
 		loadingImports: [],
 		nextLoadingId: 0,
 		hasBoundaries: false,
-		hasLayouts: false
+		hasLayouts: false,
+		hasErrorBoundaries: false
 	};
 	const routes = generateNode(node, root, context, false);
 	const imports = [...context.loadingImports];
 	const helpers = [];
-	if (context.hasBoundaries || context.hasLayouts) {
-		const reactImports = ["createElement"];
-		if (context.hasBoundaries || context.hasLayouts) reactImports.push("lazy");
-		if (context.hasBoundaries) reactImports.push("Suspense");
+	if (context.hasBoundaries || context.hasLayouts || context.hasErrorBoundaries) {
+		const reactImports = [];
+		if (context.hasBoundaries || context.hasLayouts || context.hasErrorBoundaries) reactImports.push("createElement");
+		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";`);
 	}
@@ -115,6 +189,15 @@ function generate(node, root = false, projectRoot = process.cwd()) {
   return function LayoutRoute() {
     return createElement(Layout, null, createElement(Outlet));
   };
+}`);
+	if (context.hasErrorBoundaries) helpers.push(`function createErrorBoundary(Component) {
+  return function RouteErrorBoundary() {
+    return createElement(
+      Suspense,
+      { fallback: createElement("p", null, "Loading error page...") },
+      createElement(Component),
+    );
+  };
 }`);
 	return {
 		imports,
@@ -122,34 +205,33 @@ 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}`;
+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)\.(jsx|tsx)$/.exec(entry.name);
-		if (!match) continue;
-		const [, name, extension] = match;
-		const key = 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;
@@ -163,7 +245,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);
@@ -178,7 +260,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),
           );
         }
@@ -195,15 +277,25 @@ 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" });
+	}
 	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;
+		},
+		load: (id) => {
+			if (id === ROUTES_RESOLVED_ID) return execute();
+			if (id === MANIFEST_RESOLVED_ID) return executeManifest();
+		},
 		configureServer: (server) => {
 			server.watcher.add(root);
 			server.watcher.on("all", (event, file) => {
@@ -215,9 +307,12 @@ 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]) {
+					const module = server.moduleGraph.getModuleById(id);
+					if (module) server.moduleGraph.invalidateModule(module);
+				}
 				server.ws.send({ type: "full-reload" });
 			});
 		}

package/dist/scanner.d.ts

@@ -5,6 +5,21 @@ export type Node = {
     page?: string;
     layout?: string;
     loading?: string;
+    notFound?: string;
+    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 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.4",
+  "version": "0.2.6",
   "description": "File-system routing plugin for Vite",
   "type": "module",
   "private": false,

package/types/index.d.ts

@@ -1,3 +1,9 @@
 /// <reference path="./virtual-routes.d.ts" />
 
 export { routes } from "../dist/index.js";
+export type {
+  RouteConventions,
+  RouteFileKind,
+  RouteManifestNode,
+  RoutesOptions,
+} from "../dist/index.js";

package/types/virtual-routes.d.ts

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