@troyio/vite-file-router 0.2.2 → 0.2.4

package/README.md

@@ -28,52 +28,110 @@ project root to use another directory:
 plugins: [routes("src/routes")];
 ```
 
-Each `page.jsx` or `page.tsx` becomes a route page, and each `layout.jsx` or
-`layout.tsx` becomes a lazy layout for its directory. Directories become nested
-routes. Add a `loading.jsx` or `loading.tsx` to provide a Suspense fallback for
-that directory's page and nested routes; a nested loading file provides a more
-specific fallback. Each file must default-export a React component. If both
-extensions exist for the same component, `.tsx` takes precedence. For example:
+The router scans the pages directory recursively. Each directory becomes a
+nested route, and the following files are recognized:
+
+| File | Purpose |
+| --- | --- |
+| `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. |
+
+Each file must default-export a React component. If both extensions exist for
+the same file type in one directory, `.tsx` takes precedence.
+
+For example, this structure creates a home page, user pages, and two auth
+pages:
 
 ```text
 src/pages/
-  layout.jsx
-  loading.jsx
   page.jsx
+  layout.tsx
+  loading.tsx
   users/
-    loading.tsx
     page.tsx
     [id]/
       page.tsx
+  (auth)/
+    layout.tsx
+    sign-in/
+      page.tsx
+    sign-up/
+      page.tsx
+  [...slug]/
+    page.tsx
 ```
 
-Dynamic segments such as `[id]` become `:id`; catch-all segments such as
-`[...slug]` become `*`.
+This maps to `/`, `/users`, `/users/:id`, `/sign-in`, `/sign-up`, and `/*`.
+Square-bracket segments are dynamic parameters: `[id]` becomes `:id`.
+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.
 
-Import the generated route configuration from the `virtual:routes` module in
-your application:
+### Layouts
 
-```ts
-import { routes } from "virtual:routes";
+The plugin adapts React Router's matched child route to a `children` prop. A
+layout can render that prop directly and does not need to import or render
+`Outlet`:
+
+```tsx
+import type { PropsWithChildren } from "react";
+
+export default function Layout({ children }: PropsWithChildren) {
+  return <div className="app-shell">{children}</div>;
+}
 ```
 
-The virtual module exports a `routes` array with lazy-loaded page and layout
-components.
+### Loading fallbacks
+
+Add a `loading.jsx` or `loading.tsx` beside a page or layout to show a Suspense
+fallback while that route subtree loads:
+
+```tsx
+export default function Loading() {
+  return <p>Loading...</p>;
+}
+```
+
+A nested loading file creates a more specific boundary for that directory.
+
+### 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.
+
+## Use the generated routes
+
+Import `routes` from the virtual module and pass it to React Router:
+
+```tsx
+import { createBrowserRouter, RouterProvider } from "react-router";
+import { routes } from "virtual:routes";
+
+const router = createBrowserRouter(routes);
+
+export default function App() {
+  return <RouterProvider router={router} />;
+}
+```
 
-### TypeScript
+### TypeScript setup
 
-Make sure your application TypeScript project includes Vite's client types and
-the router package's type declarations. For example, add this file as
-`src/vite-env.d.ts`:
+Add Vite's client types and the package's virtual-module declaration to your
+application TypeScript project. For example, create `src/vite-env.d.ts`:
 
 ```ts
 /// <reference types="vite/client" />
 /// <reference types="@troyio/vite-file-router" />
 ```
 
-If your `tsconfig.json` sets `compilerOptions.types`, include both
-`"vite/client"` and `"@troyio/vite-file-router"` in that list. Then restart
-the TypeScript server in your editor.
+If `tsconfig.json` sets `compilerOptions.types`, include both `"vite/client"`
+and `"@troyio/vite-file-router"` in that list. This lets TypeScript resolve
+`virtual:routes`. Restart your editor's TypeScript server if the declaration
+isn't picked up immediately.
 
 ## Build
 

package/dist/generator.d.ts

@@ -4,4 +4,13 @@ export type GeneratedRoutes = {
     helpers: string[];
     routes: string;
 };
+export type RouteConflict = {
+    routePath: string;
+    files: string[];
+};
+export declare class RouteConflictError extends Error {
+    readonly conflicts: RouteConflict[];
+    constructor(conflicts: RouteConflict[]);
+}
+export declare function findPageRouteConflicts(node: Node, pages?: Map<string, string[]>, segments?: string[], root?: boolean): RouteConflict[];
 export declare function generate(node: Node, root?: boolean, projectRoot?: string): GeneratedRoutes;

package/dist/index.js

@@ -3,6 +3,15 @@ import { genArrayFromRaw, genObjectFromRaw, genSafeVariableName } from "knitwork
 import { format } from "prettier";
 import fs from "node:fs";
 // 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.`);
+		this.conflicts = conflicts;
+		this.name = "RouteConflictError";
+	}
+};
 function getImportPath(file, projectRoot) {
 	const relativePath = path.relative(projectRoot, file).split(path.sep).join("/");
 	return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
@@ -12,18 +21,39 @@ function getRoutePath(directory) {
 	if (segment.startsWith("[...") && segment.endsWith("]")) return "*";
 	return segment.replace(/^\[(.+)\]$/, ":$1");
 }
+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]);
+	}
+	for (const child of node.children) findPageRouteConflicts(child, pages, routeSegments, false);
+	return [...pages.entries()].filter(([, files]) => files.length > 1).map(([routePath, files]) => ({
+		routePath,
+		files
+	}));
+}
 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 generateLazyComponent(file, projectRoot) {
 	return `lazy(() => import(${JSON.stringify(getImportPath(file, projectRoot))}))`;
 }
+function generateLazyLayout(file, projectRoot) {
+	return `lazy(() => import(${JSON.stringify(getImportPath(file, projectRoot))}).then(({ default: Layout }) => ({ default: withOutlet(Layout) })))`;
+}
 function generateNode(node, root, context, inheritedBoundary) {
 	const route = {};
 	const hasBoundary = inheritedBoundary || Boolean(node.loading);
-	if (!root) route.path = JSON.stringify(getRoutePath(node.directory));
+	if (node.layout) context.hasLayouts = true;
+	if (!root && !node.routeGroup) route.path = JSON.stringify(getRoutePath(node.directory));
 	let loadingComponent;
 	if (node.loading) {
 		loadingComponent = genSafeVariableName(`Loading${context.nextLoadingId++}`);
@@ -31,11 +61,11 @@ function generateNode(node, root, context, inheritedBoundary) {
 		context.hasBoundaries = true;
 	}
 	if (loadingComponent) {
-		const child = node.layout ? generateLazyComponent(node.layout, context.projectRoot) : "Outlet";
+		const child = node.layout ? generateLazyLayout(node.layout, context.projectRoot) : "Outlet";
 		route.Component = `createBoundary(${loadingComponent}, ${child})`;
 	} else if (node.layout) {
-		if (hasBoundary) route.Component = generateLazyComponent(node.layout, context.projectRoot);
-		else route.lazy = generateImport(node.layout, context.projectRoot);
+		if (hasBoundary) route.Component = generateLazyLayout(node.layout, context.projectRoot);
+		else route.lazy = generateLayoutImport(node.layout, context.projectRoot);
 	}
 	const children = [];
 	if (node.page) {
@@ -53,18 +83,26 @@ function generateNode(node, root, context, inheritedBoundary) {
 	return genObjectFromRaw(route);
 }
 function generate(node, root = false, projectRoot = process.cwd()) {
+	const conflicts = findPageRouteConflicts(node, /* @__PURE__ */ new Map(), [], root);
+	if (conflicts.length) throw new RouteConflictError(conflicts);
 	const context = {
 		projectRoot,
 		loadingImports: [],
 		nextLoadingId: 0,
-		hasBoundaries: false
+		hasBoundaries: false,
+		hasLayouts: false
 	};
 	const routes = generateNode(node, root, context, false);
 	const imports = [...context.loadingImports];
 	const helpers = [];
-	if (context.hasBoundaries) {
-		imports.unshift(`import { createElement, lazy, Suspense } from "react";`, `import { Outlet } from "react-router";`);
-		helpers.push(`function createBoundary(Fallback, Component) {
+	if (context.hasBoundaries || context.hasLayouts) {
+		const reactImports = ["createElement"];
+		if (context.hasBoundaries || context.hasLayouts) reactImports.push("lazy");
+		if (context.hasBoundaries) reactImports.push("Suspense");
+		imports.unshift(`import { ${reactImports.join(", ")} } from "react";`);
+		if (context.hasBoundaries || context.hasLayouts) imports.push(`import { Outlet } from "react-router";`);
+	}
+	if (context.hasBoundaries) helpers.push(`function createBoundary(Fallback, Component) {
   return function RouteBoundary() {
     return createElement(
       Suspense,
@@ -73,7 +111,11 @@ function generate(node, root = false, projectRoot = process.cwd()) {
     );
   };
 }`);
-	}
+	if (context.hasLayouts) helpers.push(`function withOutlet(Layout) {
+  return function LayoutRoute() {
+    return createElement(Layout, null, createElement(Outlet));
+  };
+}`);
 	return {
 		imports,
 		helpers,
@@ -85,6 +127,7 @@ function scan(directory) {
 	const node = {
 		name: path.basename(directory),
 		directory,
+		routeGroup: /^\(.+\)$/.test(path.basename(directory)),
 		children: []
 	};
 	if (!fs.existsSync(directory)) return node;
@@ -109,16 +152,44 @@ var RESOLVED_ID = `\0${MODULE_ID}`;
 function routes(directory = "src/pages") {
 	let projectRoot = "";
 	let root = "";
+	let dev = false;
+	function sortImports(imports) {
+		return imports.sort((left, right) => {
+			const leftSource = left.match(/from ["'](.+?)["']/)?.[1] ?? left;
+			const rightSource = right.match(/from ["'](.+?)["']/)?.[1] ?? right;
+			const leftIsRelative = leftSource.startsWith(".");
+			if (leftIsRelative !== rightSource.startsWith(".")) return leftIsRelative ? 1 : -1;
+			return leftSource.localeCompare(rightSource);
+		});
+	}
 	async function execute() {
-		const generated = generate(scan(root), true, projectRoot);
+		const tree = scan(root);
+		const conflicts = findPageRouteConflicts(tree);
+		if (conflicts.length) {
+			const error = new RouteConflictError(conflicts);
+			if (!dev) throw error;
+			const code = `
+        import { createElement } from "react";
+
+        const message = ${JSON.stringify(error.message)};
+
+        function RouteConflictPage() {
+          return createElement(
+            "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("pre", { style: { background: "#f3f4f6", overflowX: "auto", padding: "1rem", whiteSpace: "pre-wrap" } }, message),
+          );
+        }
+
+        export const routes = [{ path: "*", Component: RouteConflictPage }];
+      `;
+			return format(code, { parser: "typescript" });
+		}
+		const generated = generate(tree, true, projectRoot);
 		const sections = [
-			generated.imports.sort((left, right) => {
-				const leftSource = left.match(/from ["'](.+?)["']/)?.[1] ?? left;
-				const rightSource = right.match(/from ["'](.+?)["']/)?.[1] ?? right;
-				const leftIsRelative = leftSource.startsWith(".");
-				if (leftIsRelative !== rightSource.startsWith(".")) return leftIsRelative ? 1 : -1;
-				return leftSource.localeCompare(rightSource);
-			}).join("\n"),
+			sortImports(generated.imports).join("\n"),
 			generated.helpers.join("\n"),
 			`export const routes = ${genArrayFromRaw([generated.routes])};`
 		].filter(Boolean);
@@ -129,6 +200,7 @@ function routes(directory = "src/pages") {
 		configResolved(config) {
 			projectRoot = config.root;
 			root = path.resolve(projectRoot, directory);
+			dev = config.command === "serve";
 		},
 		resolveId: (id) => id === MODULE_ID ? RESOLVED_ID : void 0,
 		load: (id) => id === RESOLVED_ID ? execute() : void 0,

package/dist/scanner.d.ts

@@ -1,6 +1,7 @@
 export type Node = {
     name: string;
     directory: string;
+    routeGroup: boolean;
     page?: string;
     layout?: string;
     loading?: string;

package/package.json

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