@troyio/vite-file-router 0.3.2 → 0.4.1

package/README.md

@@ -249,6 +249,10 @@ export default function DashboardPage() {
 }
 ```
 
+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,
@@ -322,10 +326,53 @@ export default defineConfig({
 });
 ```
 
-Open the **Routes** dock to browse the nested route tree, filter by path or
-source file, and inspect parameters and special files. The panel refreshes its
-manifest automatically while the dev server is running. Vite DevTools must be
-enabled; route-tree inspection is development-only.
+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
 
@@ -360,6 +407,106 @@ 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
@@ -372,8 +519,9 @@ application TypeScript project. For example, create `src/vite-env.d.ts`:
 
 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.
+`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