@troyio/vite-file-router 0.2.3 → 0.2.5

package/README.md

@@ -28,57 +28,144 @@ 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. |
+| `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.
+
+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 `*`. Parenthesized directories are route groups and do not
-add a URL segment. Route groups can contain `page`, `layout`, and `loading`
-files just like other directories. For example, `(auth)/sign-in/page.tsx` maps
-to `/sign-in`. If two pages resolve to the same URL, the dev server displays a
-diagnostic page listing the conflicting files and explaining how to fix them.
-Production builds fail with the same diagnostic until the conflicts are fixed.
+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.
+
+### 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.
+
+## 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/index.js

@@ -33,18 +33,36 @@ 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 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))}))`;
 }
+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 (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++}`);
@@ -52,12 +70,12 @@ 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);
 	}
+	if (node.layout && !hasBoundary) route.lazy = generateRouteLazy(node, context.projectRoot, true);
 	const children = [];
 	if (node.page) {
 		const page = hasBoundary ? {
@@ -70,24 +88,43 @@ 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 = {
 		projectRoot,
 		loadingImports: [],
 		nextLoadingId: 0,
-		hasBoundaries: false
+		hasBoundaries: false,
+		hasLayouts: false,
+		hasErrorBoundaries: 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 || 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";`);
+	}
+	if (context.hasBoundaries) helpers.push(`function createBoundary(Fallback, Component) {
   return function RouteBoundary() {
     return createElement(
       Suspense,
@@ -96,7 +133,20 @@ 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));
+  };
+}`);
+	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,
 		helpers,
@@ -119,10 +169,10 @@ function scan(directory) {
 			node.children.push(scan(file));
 			continue;
 		}
-		const match = /^(page|layout|loading)\.(jsx|tsx)$/.exec(entry.name);
+		const match = /^(page|layout|loading|not-found|error)\.(jsx|tsx)$/.exec(entry.name);
 		if (!match) continue;
 		const [, name, extension] = match;
-		const key = name;
+		const key = name === "not-found" ? "notFound" : name;
 		if (!node[key] || extension === "tsx") node[key] = file;
 	}
 	return node;

package/dist/scanner.d.ts

@@ -5,6 +5,8 @@ export type Node = {
     page?: string;
     layout?: string;
     loading?: string;
+    notFound?: string;
+    error?: string;
     children: Node[];
 };
 export declare function scan(directory: string): Node;

package/package.json

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