@troyio/vite-file-router 0.4.1 → 0.6.0

package/README.md

@@ -1,536 +1,704 @@
-# vite-file-router
-
-A Vite plugin that generates a route tree from a file-based page directory.
-
-## Install
-
-```sh
-npm install @troyio/vite-file-router
-```
-
-Vite is a peer dependency and must also be installed in your project.
-
-## Configure
-
-```ts
-import { defineConfig } from "vite";
-import { routes } from "@troyio/vite-file-router";
-
-export default defineConfig({
-  plugins: [routes()],
-});
-```
-
-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 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: [
-  routes({
-    directory: "app/views",
-    conventions: {
-      page: "route",
-      layout: "shell",
-      loading: "pending",
-      notFound: "missing",
-      error: "fault",
-      loader: "load",
-      action: "mutate",
-    },
-  }),
-];
-```
-
-Omitted convention values keep their defaults: `page`, `layout`, `loading`,
-`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:
-
-| 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. |
-| `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. |
-
-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:
-
-```text
-src/pages/
-  page.jsx
-  layout.tsx
-  loading.tsx
-  loader.ts
-  users/
-    page.tsx
-    action.ts
-    [id]/
-      page.tsx
-  docs/
-    [[lang]]/
-      page.tsx
-  (auth)/
-    layout.tsx
-    sign-in/
-      page.tsx
-    sign-up/
-      page.tsx
-  [...slug]/
-    page.tsx
-```
-
-This maps to `/`, `/users`, `/users/:id`, `/docs/:lang?`, `/sign-in`,
-`/sign-up`, and `/*`. Square-bracket segments are dynamic parameters: `[id]`
-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,
-loading files, loaders, and actions, but their names do not add a URL segment.
-
-Directories whose names start with an underscore, such as `_components` or
-`_utils`, are private folders. The plugin skips them and everything nested
-inside them, so you can colocate components, hooks, and helpers next to the
-routes that use them without creating routes. A `_components/page.tsx` file is
-never routed.
-
-### Layouts
-
-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>;
-}
-```
-
-### 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>;
-}
-```
-
-### 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>;
-}
-```
-
-To get the type from the loader module instead of writing it by hand, use
-`useRouteData` from `virtual:route-helpers`. See
-[Typed params and loader data](#typed-params-and-loader-data).
-
-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
-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. 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
-
-Import `routes` from the virtual module and pass it to React Router:
-
-```tsx
-import { createBrowserRouter } from "react-router";
-import { RouterProvider } from "react-router";
-import { routes } from "virtual:routes";
-
-const router = createBrowserRouter(routes);
-
-export default function App() {
-  return <RouterProvider router={router} />;
-}
-```
-
-### 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, any `optionalParams`, 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 all generated virtual modules and
-reloads the app without requiring a server restart.
-
-### Route tree inspection
-
-The route tree can be inspected in Vite DevTools. This requires Vite 8.3 or
-later and the DevTools package:
-
-```sh
-npm install -D @vitejs/devtools
-```
-
-Enable the dock in your Vite configuration:
-
-```ts
-export default defineConfig({
-  devtools: true,
-  plugins: [routes()],
-});
-```
-
-Open the **Routes** dock to use the panel. It's development-only and needs
-Vite DevTools enabled. In the panel you can:
-
-- **Browse the route tree.** Each route shows its URL segment, full path, and
-  badges for its files: page, layout, loading, error, not-found (`404`),
-  loader, and action. You can filter by path, param, or file, collapse
-  branches, and move between routes with the arrow keys.
-- **See route details.** Select a route to see its params and files.
-- **Open files in your editor.** Click any file path. This uses Vite's built-in
-  `/__open-in-editor` endpoint, so it opens the editor Vite detects or the one
-  named in `LAUNCH_EDITOR`.
-- **Test a URL.** Enter a path such as `/users/42?tab=posts`. The panel shows
-  the matched routes, the params taken from the URL, and the page or
-  not-found page that renders. It also lists the layouts, loaders, loading
-  fallback, and error boundary that apply. Matching uses React Router's
-  `matchRoutes`, so the result agrees with the app. The matched routes are
-  highlighted in the tree.
-- **Spot route conflicts.** Pages that resolve to the same URL pattern are
-  listed at the top, with links to their files.
-- **Follow the current page.** The **Current page** card shows the URL your
-  app is on, its params, and the page that renders it. The matched routes get
-  a green dot in the tree, and the card updates as the app navigates. With
-  several app tabs open, pick which one to follow. When a tab closes, it drops
-  out of the list.
-- **See loader and action calls.** The **Timeline** tab lists each loader and
-  action call your app makes, newest first. Each entry shows the route, URL,
-  start time, duration, and outcome: returned data, a redirect with its status
-  and location, a returned response, or a thrown error. Calls of 500 ms or
-  more are highlighted. It also shows each `shouldRevalidate` decision, so
-  you can see when a loader was skipped. You can filter by call type or text,
-  and expand an entry to see a short preview of returned data and a link to
-  the loader or action file. The dev server keeps the last 200 calls, so a
-  panel opened later still sees recent history.
-
-The panel updates on its own when route files are added, removed, or renamed.
-The dev server pushes changes over a Server-Sent Events stream instead of the
-panel polling. If the dev server restarts, the panel reconnects by itself. The
-refresh button reloads the data by hand.
-
-The current page and the timeline come from a small client that
-`virtual:routes` includes on the dev server only. It reports the app's URL and
-wraps the generated loader, action, and `shouldRevalidate` handlers. It sends
-these over Vite's HMR connection. Handler results pass through unchanged, and
-only a short text preview of returned data is sent. It tracks navigation by
-wrapping `history.pushState` and `history.replaceState` and listening for
-`popstate`, and it also supports hash URLs (`#/path`). Production builds
-include none of this code.
-
-### Typed route helpers
-
-Import `routePath` from `virtual:route-helpers` to build paths for discovered
-pages. The helper is compatible with React Router's `Link`, `NavLink`,
-`navigate`, and `redirect` APIs. Dynamic parameter names and required values are
-checked from the path literal; values are URL-encoded. Splat values use the
-React Router `"*"` parameter and are encoded segment-by-segment so `/`
-separators are preserved:
-
-```tsx
-import { Link } from "react-router";
-import { routePath } from "virtual:route-helpers";
-
-export function UserLink({ userId }: { userId: string }) {
-  return (
-    <Link to={routePath("/users/:userId", { userId })}>
-      View user
-    </Link>
-  );
-}
-
-const docsPath = routePath("/docs/*", { "*": "guides/getting-started" });
-const localizedDocsPath = routePath("/docs/:lang?", { lang: "en" });
-const defaultDocsPath = routePath("/docs/:lang?");
-```
-
-Static routes and routes with only optional parameters need no parameter object.
-An optional parameter can also be omitted from the params object; its URL
-segment is removed. Unknown route patterns and missing required or extra
-parameters are rejected at runtime. Routes whose optional segment overlaps
-another page's URL pattern are reported as conflicts. The generated
-`routePatterns` export contains the discovered page paths.
-
-### Generated route types
-
-In TypeScript projects, the plugin writes `src/route-types.d.ts` when the dev
-server starts and at the start of each build. It counts a project as
-TypeScript when the Vite project root has a `tsconfig.json` or
-`jsconfig.json`. JavaScript projects without either file get no extra file.
-
-The plugin rewrites the file whenever route files are added, removed, or
-renamed, and leaves it alone when nothing changed. The file lists every
-discovered page pattern and loader module. With it in your TypeScript project,
-`routePath`, `routePatterns`, and the hooks below only accept routes that
-exist, and your editor autocompletes them:
-
-```ts
-routePath("/users/:userId", { userId }); // OK
-routePath("/usres/:userId", { userId }); // Type error: unknown route pattern
-```
-
-The `dts` option controls this. It defaults to `"auto"`, which is the behavior
-above. A path, relative to the Vite project root and ending in `.d.ts`, always
-writes the file there, even without a TypeScript config. `false` never writes
-it:
-
-```ts
-plugins: [routes({ dts: "types/route-types.d.ts" })];
-plugins: [routes({ dts: false })];
-```
-
-If your `tsconfig.json` isn't in the Vite project root, for example when Vite's
-`root` points at a subfolder, set an explicit path.
-
-Without the file, route patterns are typed as `string` and loader data as
-`unknown`, the same as before. You can commit the file so types work before
-the first dev run, or add it to `.gitignore`.
-
-### Typed params and loader data
-
-`virtual:route-helpers` also exports two hooks that wrap React Router's hooks
-with types taken from the route tree:
-
-- `useRouteParams(pattern)` returns `useParams()`, typed for that pattern.
-  Required params are `string`, optional params are `string | undefined`, and
-  a splat is a `string` under the `"*"` key.
-- `useRouteData(key)` returns `useRouteLoaderData()`, typed from the loader
-  module. The key is either a page pattern, which reads the loader in that
-  page's directory, or a loader route ID such as
-  `"file-route:src/pages/users/[userId]"`, which can read any matched loader,
-  including a parent's. It returns `undefined` when that route isn't matched,
-  just like React Router's hook.
-
-```tsx
-// src/pages/users/[userId]/loader.ts
-import type { LoaderFunctionArgs } from "react-router";
-
-export async function loader({ params }: LoaderFunctionArgs) {
-  return { name: await getUserName(params.userId!) };
-}
-
-// src/pages/users/[userId]/page.tsx
-import { useRouteData, useRouteParams } from "virtual:route-helpers";
-
-export default function UserPage() {
-  const { userId } = useRouteParams("/users/:userId"); // { userId: string }
-  const data = useRouteData("/users/:userId"); // { name: string } | undefined
-  return <h1>{data?.name ?? userId}</h1>;
-}
-```
-
-The `RouteParams<"/users/:userId">`, `RouteLoaderData<key>`, `RoutePattern`,
-and `RouteLoaderKey` types are exported from `@troyio/vite-file-router` for
-your own helpers. Loader data is typed the same way as React Router's
-`useRouteLoaderData<typeof loader>()`. JavaScript loader modules are typed as
-`any`. Both hooks throw if they're passed a pattern or key the plugin didn't
-discover.
-
-### Route preloading
-
-`virtual:routes` exports `preloadRoute(to, basename?)`. It matches a URL
-against the route tree and imports the page, layout, and loader modules of
-every matched route, so the next navigation there doesn't wait for those
-downloads. Error and action modules are left out, since they're only needed
-after an error or a form submission. Importing modules doesn't run loaders.
-Each module downloads once, however often you call it. The promise resolves to
-`false` when no route matches the URL.
-
-Call it when a user is likely to navigate, such as on link hover or focus:
-
-```tsx
-import { Link, type LinkProps } from "react-router";
-import { preloadRoute } from "virtual:routes";
-
-export function PreloadLink(props: LinkProps & { to: string }) {
-  const preload = () => void preloadRoute(props.to);
-  return <Link {...props} onMouseEnter={preload} onFocus={preload} />;
-}
-```
-
-If the router uses a `basename`, pass it as the second argument. `to` also
-accepts a partial location such as `{ pathname: "/users/42" }`.
-
-### TypeScript setup
-
-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 `tsconfig.json` sets `compilerOptions.types`, include both `"vite/client"`
-and `"@troyio/vite-file-router"` in that list. This lets TypeScript resolve
-`virtual:routes`. Make sure the generated `src/route-types.d.ts`, or the path
-you set with `dts`, is included by your `tsconfig.json`. Restart your editor's
-TypeScript server if the declarations aren't picked up immediately.
-
-## Build
-
-```sh
-npm run build
-```
-
-## Test
-
-```sh
-npm test
-```
+# vite-file-router
+
+A Vite plugin that generates a route tree from a file-based page directory.
+
+## Install
+
+```sh
+npm install @troyio/vite-file-router
+```
+
+Vite is a peer dependency and must also be installed in your project.
+
+## Configure
+
+```ts
+import { defineConfig } from "vite";
+import { routes } from "@troyio/vite-file-router";
+
+export default defineConfig({
+  plugins: [routes()],
+});
+```
+
+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 extensions. Page and component
+conventions use `.jsx` / `.tsx` files (`.tsx` takes precedence); `loader`,
+`action`, and `middleware` conventions use `.js` / `.ts` files (`.ts` takes
+precedence):
+
+```ts
+plugins: [
+  routes({
+    directory: "app/views",
+    conventions: {
+      page: "route",
+      layout: "shell",
+      loading: "pending",
+      notFound: "missing",
+      error: "fault",
+      loader: "load",
+      action: "mutate",
+      middleware: "guard",
+      hydrateFallback: "booting",
+    },
+  }),
+];
+```
+
+Omitted convention values keep their defaults: `page`, `layout`, `loading`,
+`not-found`, `error`, `loader`, `action`, `middleware`, and
+`hydrate-fallback`. 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:
+
+| 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. |
+| `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. |
+| `middleware.js` / `middleware.ts` | React Router middleware that runs before every loader and action at or below the directory. |
+| `hydrate-fallback.jsx` / `hydrate-fallback.tsx` | What renders while the first page load's loaders run. |
+
+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:
+
+```text
+src/pages/
+  page.jsx
+  layout.tsx
+  loading.tsx
+  loader.ts
+  users/
+    page.tsx
+    action.ts
+    [id]/
+      page.tsx
+  docs/
+    [[lang]]/
+      page.tsx
+  (auth)/
+    layout.tsx
+    sign-in/
+      page.tsx
+    sign-up/
+      page.tsx
+  [...slug]/
+    page.tsx
+```
+
+This maps to `/`, `/users`, `/users/:id`, `/docs/:lang?`, `/sign-in`,
+`/sign-up`, and `/*`. Square-bracket segments are dynamic parameters: `[id]`
+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,
+loading files, loaders, and actions, but their names do not add a URL segment.
+
+Directories whose names start with an underscore, such as `_components` or
+`_utils`, are private folders. The plugin skips them and everything nested
+inside them, so you can colocate components, hooks, and helpers next to the
+routes that use them without creating routes. A `_components/page.tsx` file is
+never routed.
+
+### Layouts
+
+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>;
+}
+```
+
+### 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.
+
+Loading files cover lazy page code, not loader time. On later navigations,
+React Router keeps the current page on screen while loaders run, so show
+pending UI with `useNavigation()` in a layout.
+
+### Hydrate fallbacks
+
+On the first page load, nothing renders until the matched routes' loaders and
+lazy modules are ready. Add a `hydrate-fallback.jsx` or `hydrate-fallback.tsx`
+to show something in the meantime:
+
+```tsx
+export default function HydrateFallback() {
+  return <p>Loading the app...</p>;
+}
+```
+
+The file becomes the directory route's React Router `HydrateFallback`.
+React Router renders the nearest one at or above the first route that is
+still loading, below the layouts of the routes above it. A layout in the same
+directory as the fallback doesn't wrap it. It only shows on the first load;
+later navigations keep the current page on screen instead.
+
+Hydrate fallbacks are imported up front rather than lazily, because they
+render before any route module has loaded. Keep them small: they're part of
+your app's initial bundle.
+
+### 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>;
+}
+```
+
+### 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>;
+}
+```
+
+To get the type from the loader module instead of writing it by hand, use
+`useRouteData` from `virtual:route-helpers`. See
+[Typed params and loader data](#typed-params-and-loader-data).
+
+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.
+
+### Middleware
+
+Add a `middleware.ts` (or `.js`) file to run code before the loaders and
+actions at or below its directory, for example to check a session, log
+requests, or share data through React Router's `context`. Export a function,
+or an array of functions, as `middleware` or as the default export:
+
+```ts
+// src/pages/context.ts
+import { createContext } from "react-router";
+
+export const userContext = createContext<User | null>(null);
+```
+
+```ts
+// src/pages/(app)/middleware.ts
+import { redirect, type MiddlewareFunction } from "react-router";
+import { userContext } from "../context";
+
+export const middleware: MiddlewareFunction[] = [
+  async ({ request, context }, next) => {
+    const user = await getUser(request);
+    if (!user) throw redirect("/sign-in");
+    context.set(userContext, user);
+    await next();
+  },
+];
+```
+
+```ts
+// src/pages/(app)/dashboard/loader.ts
+import type { LoaderFunctionArgs } from "react-router";
+import { userContext } from "../../context";
+
+export function loader({ context }: LoaderFunctionArgs) {
+  return { user: context.get(userContext) };
+}
+```
+
+The plugin attaches the file to the directory's route through React Router's
+route `middleware` option, so React Router's rules apply: parent middleware
+runs before child middleware, `next()` runs the rest of the chain and the
+loaders or action, and a function that doesn't call `next()` has it called
+for it afterward. Throwing a redirect stops the navigation, and other thrown
+errors render the nearest error file. Middleware runs on every navigation,
+even when no route has a loader. React Router 8 supports route middleware
+without a future flag.
+
+React Router can't load middleware through a route's `lazy()` function, so
+the generated route imports the file the first time its middleware runs.
+`preloadRoute()` imports it ahead of time along with the route's other
+modules.
+
+Middleware runs in the browser here, like loaders and actions. As with route
+guards, it isn't a security boundary: protect data in your server or API too.
+
+### 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. 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
+
+Import `routes` from the virtual module and pass it to React Router:
+
+```tsx
+import { createBrowserRouter } from "react-router";
+import { RouterProvider } from "react-router";
+import { routes } from "virtual:routes";
+
+const router = createBrowserRouter(routes);
+
+export default function App() {
+  return <RouterProvider router={router} />;
+}
+```
+
+### 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, any `optionalParams`, 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 all generated virtual modules and
+reloads the app without requiring a server restart.
+
+### Route tree inspection
+
+The route tree can be inspected in Vite DevTools. This requires Vite 8.3 or
+later and the DevTools package:
+
+```sh
+npm install -D @vitejs/devtools
+```
+
+Enable the dock in your Vite configuration:
+
+```ts
+export default defineConfig({
+  devtools: true,
+  plugins: [routes()],
+});
+```
+
+Open the **Routes** dock to use the panel. It's development-only and needs
+Vite DevTools enabled. The panel has three pages, listed in a sidebar (or a
+top bar when the dock is narrow): **Routes**, **Timeline**, and **Generated
+code**. The page you're on is kept in the URL hash, so reloading the panel
+stays on it. In the panel you can:
+
+- **Browse the route tree.** Each route shows its URL segment, full path, and
+  badges for its files: page, layout, loading, error, not-found (`404`),
+  loader, action, middleware (`mw`), and hydrate fallback (`hydrate`). You
+  can filter by path, param, or file, collapse
+  branches, and move between routes with the arrow keys.
+- **See route details.** Select a route to see its params, files, and
+  warnings. For a route with a loader or action, the **Data calls** section
+  shows how many calls it made, their average and slowest duration, errors,
+  and the last outcome, with a link to those calls in the timeline.
+- **Open files in your editor.** Click any file path. This uses Vite's built-in
+  `/__open-in-editor` endpoint, so it opens the editor Vite detects or the one
+  named in `LAUNCH_EDITOR`.
+- **Test a URL.** Enter a path such as `/users/42?tab=posts`. The panel shows
+  the matched routes, the params taken from the URL, and the page or
+  not-found page that renders. It also lists the layouts, loaders, loading
+  fallback, and error boundary that apply. Matching uses React Router's
+  `matchRoutes`, so the result agrees with the app. The matched routes are
+  highlighted in the tree.
+- **Open a route in your app.** Route details have an **Open in app** button.
+  For routes with params, it's a short form with a field for each param
+  (optional params can be left empty, and a catch-all takes the rest of the
+  path). The panel remembers the values you used last for each route. A
+  button on each tree row does the same, and the URL tester has one for the
+  tested URL. The app tab you follow navigates with React Router, without a
+  page reload, and Back returns to where it was. If no app tab is connected,
+  the URL opens in a new browser tab. URLs are paths in your app; if your
+  router uses a `basename`, include it.
+- **Spot route conflicts.** Pages that resolve to the same URL pattern are
+  listed at the top, with links to their files.
+- **Catch missing files.** The warnings list at the top, and a `warn` badge in
+  the tree, flag:
+  - a route with a loader, action, or middleware but no `error` file at or
+    above it, so errors it throws show React Router's default error screen;
+  - a missing root `not-found` file (a hint when a root `error` file handles
+    unknown URLs instead);
+  - a loader or action file that doesn't export a function named `loader` or
+    `action`, or a middleware file with no default or `middleware` export.
+
+  Loaders the timeline measures at 500 ms or more get a hint as well.
+  Loading files only cover lazy page code, not loader time, so show pending
+  UI with `useNavigation()` in a layout instead. Warnings update when route
+  files change.
+- **Follow the current page.** The **Current page** card shows the URL your
+  app is on, its params, and the page that renders it. The matched routes get
+  a green dot in the tree, and the card updates as the app navigates. With
+  several app tabs open, pick which one to follow. When a tab closes, it drops
+  out of the list.
+- **See loader and action calls.** The **Timeline** tab lists each loader,
+  action, and middleware call your app makes, newest first. Middleware
+  entries show the time spent in the middleware itself, not counting what
+  `next()` runs. Each entry shows the route, URL, start time, duration, and
+  outcome: returned data, a redirect with its status and location, a returned
+  response, a thrown error, or `next()` for middleware that passed control
+  on. Calls of 500 ms or
+  more are highlighted. It also shows each `shouldRevalidate` decision, so
+  you can see when a loader was skipped. You can filter by call type, text,
+  or route. The dev server keeps the last 200 calls, so a panel opened later
+  still sees recent history.
+- **Read the generated code.** The **Generated code** page shows
+  `virtual:routes`, `virtual:route-manifest`, `virtual:route-helpers`, and
+  the route types declaration file exactly as the plugin generates them, with
+  line numbers, size, simple highlighting, and a copy button. For
+  `virtual:routes`, switch between the dev server version, which includes the
+  DevTools client, and the build version. The page refreshes when route files
+  change, and a module that can't be generated (for example during a route
+  conflict) shows its error.
+- **Inspect a call.** Expand a timeline entry to see its route params, the
+  request, and for actions the submitted form fields or body. Returned data
+  appears as a collapsible JSON tree with a copy button. Responses show their
+  status, headers, and body, and errors show their name, message, and stack.
+  `shouldRevalidate` entries show the URL being left and the next URL, the
+  form method, and the action status.
+
+The panel updates on its own when route files are added, removed, or renamed.
+The dev server pushes changes over a Server-Sent Events stream instead of the
+panel polling. If the dev server restarts, the panel reconnects by itself. The
+refresh button reloads the data by hand.
+
+The current page and the timeline come from a small client that
+`virtual:routes` includes on the dev server only. It reports the app's URL and
+wraps the generated loader, action, middleware, and `shouldRevalidate`
+handlers. It sends these over Vite's HMR connection, and receives the panel's
+**Open in app** requests over it. Handler results pass through unchanged. The
+panel gets a capped copy of each call: up to 8 KB of returned data, and up to
+4 KB each for bodies and stacks. Circular references, `Map`, `Set`, and
+`bigint` values are converted so serialization doesn't fail. Request and
+response bodies are read from clones, so your handlers and React Router can
+still read them. It tracks navigation by wrapping `history.pushState` and
+`history.replaceState` and listening for `popstate`, and it also supports hash
+URLs (`#/path`). Production builds include none of this code.
+
+### Build-time route warnings
+
+`vite build` prints the same missing-file warnings the DevTools panel shows,
+once per build, grouped by route:
+
+```text
+vite-file-router found 2 route warnings:
+
+  /users
+    - This route has a loader but no error file at or above it, so errors it throws show React Router's default error screen. [no-error-boundary]
+      src/pages/users/loader.ts
+    - This loader file doesn't export a function named "loader", so the route loads no data. [missing-export]
+      src/pages/users/loader.ts
+```
+
+Hints, such as a root `error` file handling unknown URLs in place of a
+`not-found` page, only appear in the panel. The dev server doesn't print
+warnings either; the panel shows them there.
+
+Use the `warnings` option to change this:
+
+```ts
+routes({ warnings: "error" }); // fail the build, for example in CI
+routes({ warnings: false }); // don't check
+routes({
+  warnings: { level: "error", ignore: ["no-not-found"] },
+});
+```
+
+The warning kinds are `no-error-boundary`, `no-not-found`, and
+`missing-export`.
+
+### Typed route helpers
+
+Import `routePath` from `virtual:route-helpers` to build paths for discovered
+pages. The helper is compatible with React Router's `Link`, `NavLink`,
+`navigate`, and `redirect` APIs. Dynamic parameter names and required values are
+checked from the path literal; values are URL-encoded. Splat values use the
+React Router `"*"` parameter and are encoded segment-by-segment so `/`
+separators are preserved:
+
+```tsx
+import { Link } from "react-router";
+import { routePath } from "virtual:route-helpers";
+
+export function UserLink({ userId }: { userId: string }) {
+  return (
+    <Link to={routePath("/users/:userId", { userId })}>
+      View user
+    </Link>
+  );
+}
+
+const docsPath = routePath("/docs/*", { "*": "guides/getting-started" });
+const localizedDocsPath = routePath("/docs/:lang?", { lang: "en" });
+const defaultDocsPath = routePath("/docs/:lang?");
+```
+
+Static routes and routes with only optional parameters need no parameter object.
+An optional parameter can also be omitted from the params object; its URL
+segment is removed. Unknown route patterns and missing required or extra
+parameters are rejected at runtime. Routes whose optional segment overlaps
+another page's URL pattern are reported as conflicts. The generated
+`routePatterns` export contains the discovered page paths.
+
+### Generated route types
+
+In TypeScript projects, the plugin writes `src/route-types.d.ts` when the dev
+server starts and at the start of each build. It counts a project as
+TypeScript when the Vite project root has a `tsconfig.json` or
+`jsconfig.json`. JavaScript projects without either file get no extra file.
+
+The plugin rewrites the file whenever route files are added, removed, or
+renamed, and leaves it alone when nothing changed. The file lists every
+discovered page pattern and loader module. With it in your TypeScript project,
+`routePath`, `routePatterns`, and the hooks below only accept routes that
+exist, and your editor autocompletes them:
+
+```ts
+routePath("/users/:userId", { userId }); // OK
+routePath("/usres/:userId", { userId }); // Type error: unknown route pattern
+```
+
+The `dts` option controls this. It defaults to `"auto"`, which is the behavior
+above. A path, relative to the Vite project root and ending in `.d.ts`, always
+writes the file there, even without a TypeScript config. `false` never writes
+it:
+
+```ts
+plugins: [routes({ dts: "types/route-types.d.ts" })];
+plugins: [routes({ dts: false })];
+```
+
+If your `tsconfig.json` isn't in the Vite project root, for example when Vite's
+`root` points at a subfolder, set an explicit path.
+
+Without the file, route patterns are typed as `string` and loader data as
+`unknown`, the same as before. You can commit the file so types work before
+the first dev run, or add it to `.gitignore`.
+
+### Typed params and loader data
+
+`virtual:route-helpers` also exports two hooks that wrap React Router's hooks
+with types taken from the route tree:
+
+- `useRouteParams(pattern)` returns `useParams()`, typed for that pattern.
+  Required params are `string`, optional params are `string | undefined`, and
+  a splat is a `string` under the `"*"` key.
+- `useRouteData(key)` returns `useRouteLoaderData()`, typed from the loader
+  module. The key is either a page pattern, which reads the loader in that
+  page's directory, or a loader route ID such as
+  `"file-route:src/pages/users/[userId]"`, which can read any matched loader,
+  including a parent's. It returns `undefined` when that route isn't matched,
+  just like React Router's hook.
+
+```tsx
+// src/pages/users/[userId]/loader.ts
+import type { LoaderFunctionArgs } from "react-router";
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  return { name: await getUserName(params.userId!) };
+}
+
+// src/pages/users/[userId]/page.tsx
+import { useRouteData, useRouteParams } from "virtual:route-helpers";
+
+export default function UserPage() {
+  const { userId } = useRouteParams("/users/:userId"); // { userId: string }
+  const data = useRouteData("/users/:userId"); // { name: string } | undefined
+  return <h1>{data?.name ?? userId}</h1>;
+}
+```
+
+The `RouteParams<"/users/:userId">`, `RouteLoaderData<key>`, `RoutePattern`,
+and `RouteLoaderKey` types are exported from `@troyio/vite-file-router` for
+your own helpers. Loader data is typed the same way as React Router's
+`useRouteLoaderData<typeof loader>()`. JavaScript loader modules are typed as
+`any`. Both hooks throw if they're passed a pattern or key the plugin didn't
+discover.
+
+### Route preloading
+
+`virtual:routes` exports `preloadRoute(to, basename?)`. It matches a URL
+against the route tree and imports the page, layout, and loader modules of
+every matched route, so the next navigation there doesn't wait for those
+downloads. Error and action modules are left out, since they're only needed
+after an error or a form submission. Importing modules doesn't run loaders.
+Each module downloads once, however often you call it. The promise resolves to
+`false` when no route matches the URL.
+
+Call it when a user is likely to navigate, such as on link hover or focus:
+
+```tsx
+import { Link, type LinkProps } from "react-router";
+import { preloadRoute } from "virtual:routes";
+
+export function PreloadLink(props: LinkProps & { to: string }) {
+  const preload = () => void preloadRoute(props.to);
+  return <Link {...props} onMouseEnter={preload} onFocus={preload} />;
+}
+```
+
+If the router uses a `basename`, pass it as the second argument. `to` also
+accepts a partial location such as `{ pathname: "/users/42" }`.
+
+### TypeScript setup
+
+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 `tsconfig.json` sets `compilerOptions.types`, include both `"vite/client"`
+and `"@troyio/vite-file-router"` in that list. This lets TypeScript resolve
+`virtual:routes`. Make sure the generated `src/route-types.d.ts`, or the path
+you set with `dts`, is included by your `tsconfig.json`. Restart your editor's
+TypeScript server if the declarations aren't picked up immediately.
+
+## Build
+
+```sh
+npm run build
+```
+
+## Test
+
+```sh
+npm test
+```