@troyio/vite-file-router 0.2.8 → 0.3.1

package/README.md

@@ -29,9 +29,10 @@ directory:
 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:
+You can also configure the directory and special filenames together.
+Convention values are filename stems without extensions. Page and component
+conventions use `.jsx` / `.tsx` files (`.tsx` takes precedence); `loader` and
+`action` conventions use `.js` / `.ts` files (`.ts` takes precedence):
 
 ```ts
 plugins: [
@@ -43,13 +44,16 @@ plugins: [
       loading: "pending",
       notFound: "missing",
       error: "fault",
+      loader: "load",
+      action: "mutate",
     },
   }),
 ];
 ```
 
 Omitted convention values keep their defaults: `page`, `layout`, `loading`,
-`not-found`, and `error`. Each convention must have a unique filename stem.
+`not-found`, `error`, `loader`, and `action`. 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:
@@ -61,9 +65,13 @@ nested route, and the following files are recognized:
 | `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. |
+| `loader.js` / `loader.ts` | A React Router loader for the directory's route and its descendants. |
+| `action.js` / `action.ts` | A React Router action selected when that directory route is the submission target. |
 
-Each file must default-export a React component. If both extensions exist for
-the same file type in one directory, `.tsx` takes precedence.
+Component files must default-export a React component. Loader and action
+modules must named-export their handler as `loader` or `action`; if both
+supported extensions exist for the same convention in one directory, the
+TypeScript file takes precedence.
 
 For example, this structure creates a home page, user pages, and two auth
 pages:
@@ -73,8 +81,10 @@ src/pages/
   page.jsx
   layout.tsx
   loading.tsx
+  loader.ts
   users/
     page.tsx
+    action.ts
     [id]/
       page.tsx
   docs/
@@ -95,8 +105,8 @@ This maps to `/`, `/users`, `/users/:id`, `/docs/:lang?`, `/sign-in`,
 becomes `:id`; double-bracket segments are optional dynamic parameters, so
 `[[lang]]` becomes `:lang?` and matches both `/docs` and `/docs/en`.
 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.
+are route groups; they organize files and can have their own page, layout,
+loading files, loaders, and actions, but their names do not add a URL segment.
 
 ### Layouts
 
@@ -157,6 +167,87 @@ export default function ErrorPage() {
 }
 ```
 
+### Loaders, actions, and route guards
+
+Add a `loader.ts` / `loader.js` or `action.ts` / `action.js` beside the route
+files and export a named handler. The generated React Router route calls these
+handlers with React Router's loader/action arguments. Their returned values,
+thrown errors, and redirect responses use React Router's normal data-router
+behavior. A loader on a directory route runs when that route matches, including
+when a descendant URL matches. An action runs only when its route is selected
+as the submission target; a parent action does not automatically handle
+submissions targeting child routes.
+
+A loader module may also export `shouldRevalidate(args)` to control the route's
+React Router `shouldRevalidate` option. It receives the same arguments as
+`shouldRevalidate` and must synchronously return a boolean:
+
+```ts
+import type { LoaderFunctionArgs, ShouldRevalidateFunctionArgs } from "react-router";
+
+export function shouldRevalidate({ nextUrl, defaultShouldRevalidate }: ShouldRevalidateFunctionArgs) {
+  if (nextUrl.searchParams.get("refresh") === "never") return false;
+  return defaultShouldRevalidate;
+}
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  return getDashboardData(request);
+}
+```
+
+Use a loader to redirect users who should not enter a protected route subtree.
+For example, `src/pages/dashboard/loader.ts` can guard `/dashboard` and all of
+its nested pages:
+
+```ts
+import { redirect, type LoaderFunctionArgs } from "react-router";
+import { getUserForRequest } from "../../lib/auth.server";
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  const user = await getUserForRequest(request);
+  if (!user) {
+    const returnTo = new URL(request.url).pathname;
+    throw redirect(`/sign-in?returnTo=${encodeURIComponent(returnTo)}`);
+  }
+  return null;
+}
+```
+
+Actions use the same pattern and receive React Router's `ActionFunctionArgs`:
+
+```ts
+import { redirect, type ActionFunctionArgs } from "react-router";
+
+export async function action({ request }: ActionFunctionArgs) {
+  const formData = await request.formData();
+  await updateProfile(formData);
+  return redirect("/profile");
+}
+```
+
+When a directory has both a page and a loader, that page is generated as an
+index child route, while the loader remains on the directory route so it also
+runs for descendant pages. Read the directory loader's result in the page with
+React Router's `useRouteLoaderData`. The generated route ID is
+`file-route:` followed by the directory path relative to the Vite project
+root, with `/` separators:
+
+```tsx
+import { useRouteLoaderData } from "react-router";
+
+export default function DashboardPage() {
+  const data = useRouteLoaderData<{ message: string }>(
+    "file-route:src/pages/dashboard",
+  );
+  return <h1>{data?.message}</h1>;
+}
+```
+
+The authentication and mutation functions above are application code. A
+client-side route guard controls navigation and presentation; it is not a
+security boundary. Protect data and mutations in the server/API layer as well,
+and do not rely on a parent loader running before descendant loaders.
+
 ### Dynamic routes and route groups
 
 Two pages must not resolve to the same URL. This includes pages with the same
@@ -174,7 +265,8 @@ first.
 Import `routes` from the virtual module and pass it to React Router:
 
 ```tsx
-import { createBrowserRouter, RouterProvider } from "react-router";
+import { createBrowserRouter } from "react-router";
+import { RouterProvider } from "react-router";
 import { routes } from "virtual:routes";
 
 const router = createBrowserRouter(routes);

package/dist/index.js

@@ -9,7 +9,9 @@ var DEFAULT_CONVENTIONS = {
 	layout: "layout",
 	loading: "loading",
 	notFound: "not-found",
-	error: "error"
+	error: "error",
+	loader: "loader",
+	action: "action"
 };
 function getRouteSegment(name) {
 	if (name.startsWith("[...") && name.endsWith("]")) return "*";
@@ -54,12 +56,15 @@ function scan(directory, conventions = DEFAULT_CONVENTIONS) {
 			node.children.push(scan(file, conventions));
 			continue;
 		}
-		const match = /^(.*)\.(jsx|tsx)$/.exec(entry.name);
+		const match = /^(.*)\.(jsx|tsx|js|ts)$/.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;
+		const isDataModule = kind === "loader" || kind === "action";
+		if (!(isDataModule ? ["js", "ts"] : ["jsx", "tsx"]).includes(extension)) continue;
+		const preferredExtension = isDataModule ? "ts" : "tsx";
+		if (!node[kind] || extension === preferredExtension) node[kind] = file;
 	}
 	return node;
 }
@@ -127,9 +132,19 @@ function generateImport(file, projectRoot) {
     Component: (await import(${JSON.stringify(getImportPath(file, projectRoot))})).default
   })`;
 }
-function generateRouteLazy(node, projectRoot, includeLayout) {
+function generateRouteLazy(node, projectRoot, includeLayout, includeLoader) {
 	const properties = [];
 	if (includeLayout && node.layout) properties.push(`Component: withOutlet((await import(${JSON.stringify(getImportPath(node.layout, projectRoot))})).default)`);
+	if (includeLoader && node.loader) return `async () => {
+      const loaderModule = await import(${JSON.stringify(getImportPath(node.loader, projectRoot))});
+      return {
+        loader: loaderModule.loader,
+        ...(typeof loaderModule.shouldRevalidate === "function"
+          ? { shouldRevalidate: loaderModule.shouldRevalidate }
+          : {}),
+        ${properties.join(",\n        ")}
+      };
+    }`;
 	return `async () => ({ ${properties.join(", ")} })`;
 }
 function generateLazyComponent(file, projectRoot) {
@@ -138,15 +153,23 @@ function generateLazyComponent(file, projectRoot) {
 function generateLazyLayout(file, projectRoot) {
 	return `lazy(() => import(${JSON.stringify(getImportPath(file, projectRoot))}).then(({ default: Layout }) => ({ default: withOutlet(Layout) })))`;
 }
+function generateDataHandler(file, projectRoot) {
+	return `async (args) => (await import(${JSON.stringify(getImportPath(file, projectRoot))})).action(args)`;
+}
+function getRouteId(directory, projectRoot) {
+	return `file-route:${path.relative(projectRoot, directory).split(path.sep).join("/") || "."}`;
+}
 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.loader) route.id = JSON.stringify(getRouteId(node.directory, context.projectRoot));
 	if (node.error) {
 		context.hasErrorBoundaries = true;
 		route.ErrorBoundary = `createErrorBoundary(${generateLazyComponent(node.error, context.projectRoot)})`;
 	}
+	if (node.action) route.action = generateDataHandler(node.action, context.projectRoot);
 	let loadingComponent;
 	if (node.loading) {
 		loadingComponent = genSafeVariableName(`Loading${context.nextLoadingId++}`);
@@ -159,15 +182,17 @@ function generateNode(node, root, context, inheritedBoundary) {
 	} else if (node.layout) {
 		if (hasBoundary) route.Component = generateLazyLayout(node.layout, context.projectRoot);
 	}
-	if (node.layout && !hasBoundary) route.lazy = generateRouteLazy(node, context.projectRoot, true);
+	if (node.layout && !hasBoundary || node.loader) route.lazy = generateRouteLazy(node, context.projectRoot, Boolean(node.layout && !hasBoundary), Boolean(node.loader));
 	const children = [];
 	if (node.page) {
 		const page = hasBoundary ? {
 			index: "true",
-			Component: generateLazyComponent(node.page, context.projectRoot)
+			Component: generateLazyComponent(node.page, context.projectRoot),
+			...node.action ? { action: generateDataHandler(node.action, context.projectRoot) } : {}
 		} : {
 			index: "true",
-			lazy: generateImport(node.page, context.projectRoot)
+			lazy: generateImport(node.page, context.projectRoot),
+			...node.action ? { action: generateDataHandler(node.action, context.projectRoot) } : {}
 		};
 		children.push(genObjectFromRaw(page));
 	}

package/dist/scanner.d.ts

@@ -7,9 +7,11 @@ export type Node = {
     loading?: string;
     notFound?: string;
     error?: string;
+    loader?: string;
+    action?: string;
     children: Node[];
 };
-export type RouteFileKind = "page" | "layout" | "loading" | "notFound" | "error";
+export type RouteFileKind = "page" | "layout" | "loading" | "notFound" | "error" | "loader" | "action";
 export type RouteConventions = Partial<Record<RouteFileKind, string>>;
 export type RouteManifestNode = {
     segment: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@troyio/vite-file-router",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "description": "File-system routing plugin for Vite",
   "type": "module",
   "private": false,
@@ -38,8 +38,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.6.4",
-    "@vitejs/devtools-kit": "^0.8.2",
     "@types/node": "^24.19.2",
+    "@vitejs/devtools-kit": "^0.8.2",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
     "typescript": "~6.0.3",
     "vite": "^8.3.5"
   },