@troyio/vite-file-router 0.4.0 → 0.4.1

package/README.md

@@ -326,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
 
@@ -366,26 +409,35 @@ another page's URL pattern are reported as conflicts. The generated
 
 ### Generated route types
 
-When the dev server starts and at the start of each build, the plugin writes
-`src/route-types.d.ts`. It 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:
+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
 ```
 
-Change the output path, or turn the file off, with the `dts` option. The path
-is relative to the Vite project root and must end in `.d.ts`:
+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`.