@troyio/vite-file-router 0.2.3 → 0.2.4

package/README.md

@@ -28,57 +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 `*`. 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.
+
+### 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

@@ -38,12 +38,21 @@ function generateImport(file, projectRoot) {
     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 (node.layout) context.hasLayouts = true;
 	if (!root && !node.routeGroup) route.path = JSON.stringify(getRoutePath(node.directory));
 	let loadingComponent;
 	if (node.loading) {
@@ -52,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) {
@@ -80,14 +89,20 @@ function generate(node, root = false, projectRoot = process.cwd()) {
 		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,
@@ -96,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,

package/package.json

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