@troyio/vite-file-router 0.4.0 → 0.5.0

package/dist/devtools-app.d.ts

@@ -0,0 +1,97 @@
+import { type RouteMatchResult } from "./devtools";
+import type { RouteManifestNode } from "./scanner";
+/** HMR events the dev-only client in `virtual:routes` sends to the server. */
+export declare const APP_LOCATION_EVENT = "vite-file-router:location";
+export declare const APP_DATA_EVENT = "vite-file-router:data";
+/** Sent from the server to the app: navigate one tab to a URL. */
+export declare const APP_NAVIGATE_EVENT = "vite-file-router:navigate";
+/**
+ * Checks a URL the panel asks an app tab to open. Only same-origin paths are
+ * allowed, so the panel can't send the app to another site.
+ */
+export declare function isAppPath(url: unknown): url is string;
+/** The part of Vite's HMR client used to message one app tab. */
+export type AppClient = {
+    send(event: string, payload?: unknown): void;
+};
+/** An open browser tab running the app, and the route it's on. */
+export type AppTab = {
+    id: string;
+    url: string;
+    title: string;
+    connectedAt: number;
+    updatedAt: number;
+    match: RouteMatchResult;
+};
+/** `next` means middleware passed control on to the next handler. */
+export type RouteDataOutcome = "data" | "response" | "redirect" | "error" | "next";
+/** One loader, action, or `shouldRevalidate` call reported by the app. */
+export type RouteDataEvent = {
+    /** Increasing number, unique for this dev-server session. */
+    id: number;
+    tabId: string;
+    type: "loader" | "action" | "middleware" | "revalidate";
+    /** React Router route ID, `file-route:` plus the route directory. */
+    routeId: string;
+    url?: string;
+    method?: string;
+    startedAt: number;
+    duration?: number;
+    outcome?: RouteDataOutcome;
+    status?: number;
+    location?: string;
+    message?: string;
+    /** A short JSON preview of returned data. */
+    preview?: string;
+    /** For `revalidate` events: whether the loader runs. */
+    decision?: boolean;
+    defaultShouldRevalidate?: boolean;
+    /** Route params passed to the handler. */
+    params?: Record<string, string>;
+    /** The submitted body of an action request. */
+    body?: RouteRequestBody;
+    /** Serialized returned (or thrown, non-`Error`) data, capped in size. */
+    data?: string;
+    dataTruncated?: boolean;
+    /** Response headers, from a `Response` or React Router's `data()`. */
+    headers?: [string, string][];
+    responseBody?: string;
+    errorName?: string;
+    stack?: string;
+    /** For `revalidate` events: the URL being left. */
+    currentUrl?: string;
+    formMethod?: string;
+    actionStatus?: number;
+};
+export type RouteRequestBody = {
+    kind: "form";
+    entries: [string, string][];
+} | {
+    kind: "text";
+    contentType?: string;
+    text: string;
+};
+/**
+ * Validates an event from the browser. Anything a page sends over the HMR
+ * channel is untrusted, so only known fields of the expected types are kept.
+ */
+export declare function sanitizeDataEvent(input: unknown, id: number): RouteDataEvent | undefined;
+/**
+ * Tracks the app tabs connected to the dev server and their recent loader
+ * and action calls, and tells the panel when either changes.
+ */
+export declare function createAppTracker(options: {
+    getManifest: () => RouteManifestNode;
+    onTabsChange: (tabs: AppTab[]) => void;
+    onActivity: (event: RouteDataEvent) => void;
+}): {
+    tabs: () => AppTab[];
+    activity: () => RouteDataEvent[];
+    updateLocation(client: object, input: unknown): Promise<void>;
+    /** The HMR client for an app tab, to send it events such as navigation. */
+    clientFor(tabId: string): AppClient | undefined;
+    disconnect(client: object): void;
+    /** Re-matches every tab, for example after route files change. */
+    rematch(): Promise<void>;
+    record(input: unknown): void;
+};

package/dist/devtools.d.ts

@@ -0,0 +1,75 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteConflict } from "./generator";
+import type { RouteFileKind, RouteManifestNode } from "./scanner";
+export declare const ROUTE_INSPECTOR_PATH = "/__vite-file-router/";
+export declare const ROUTE_INSPECTOR_DATA_PATH = "/__vite-file-router-data";
+export declare const ROUTE_INSPECTOR_EVENTS_PATH = "/__vite-file-router-events";
+export declare const ROUTE_INSPECTOR_MATCH_PATH = "/__vite-file-router-match";
+export declare const ROUTE_INSPECTOR_NAVIGATE_PATH = "/__vite-file-router-navigate";
+export type RouteInspectorState = {
+    /** Absolute Vite project root, so the panel can open files in an editor. */
+    projectRoot: string;
+    /** The routes directory, relative to the project root with `/` separators. */
+    directory: string;
+    manifest: RouteManifestNode;
+    conflicts: RouteConflict[];
+    warnings: RouteWarning[];
+};
+export type RouteWarningKind = "no-error-boundary" | "no-not-found" | "missing-export";
+export type RouteWarning = {
+    kind: RouteWarningKind;
+    severity: "warning" | "info";
+    /**
+     * The route's position in the manifest: `0` for the root, then child
+     * indexes joined with dots, such as `0.2.1`.
+     */
+    key: string;
+    fullPath: string;
+    message: string;
+    /** Project-relative files the warning is about. */
+    files: string[];
+};
+/** Whether module source code (probably) has a named export. */
+export declare function hasNamedExport(source: string, name: string): boolean;
+/**
+ * Finds routes that are missing a file they likely need: an error file for a
+ * loader, action, or middleware, a root not-found page, or the expected export
+ * of a data module. `readSource` reads a project-relative file.
+ */
+export declare function findRouteWarnings(manifest: RouteManifestNode, readSource?: (file: string) => string | undefined): RouteWarning[];
+export type RouteMatchSegment = {
+    fullPath: string;
+    segment: string | null;
+    routeGroup: boolean;
+    files: Partial<Record<RouteFileKind, string>>;
+};
+export type RouteMatchResult = {
+    matched: false;
+    pathname: string;
+} | {
+    matched: true;
+    pathname: string;
+    params: Record<string, string | undefined>;
+    /** Directory routes from the root down to the matched route. */
+    chain: RouteMatchSegment[];
+    page?: string;
+    notFound?: string;
+    layouts: string[];
+    loaders: string[];
+    middleware: string[];
+    loading?: string;
+    error?: string;
+};
+export declare function matchRouteManifest(manifest: RouteManifestNode, url: string): Promise<RouteMatchResult>;
+/** Pushes route state to open DevTools panels over Server-Sent Events. */
+export declare function createRouteEventStream(getState: () => RouteInspectorState, 
+/** Extra events sent to each panel when it connects. */
+getSnapshot?: () => [event: string, data: unknown][]): {
+    clients: Set<ServerResponse<IncomingMessage>>;
+    connect(request: IncomingMessage, response: ServerResponse): void;
+    /** Coalesces bursts of file events (such as a folder rename) into one push. */
+    notify(): void;
+    /** Sends a named event to every connected panel right away. */
+    broadcast(event: string, data: unknown): void;
+    close(): void;
+};

package/dist/generator.d.ts

@@ -1,4 +1,11 @@
 import { type Node } from "./scanner";
+export type GenerateOptions = {
+    /**
+     * Add a client that reports the app's location and its loader and action
+     * calls to the DevTools panel over Vite's HMR channel. Dev server only.
+     */
+    devClient?: boolean;
+};
 export type GeneratedRoutes = {
     imports: string[];
     helpers: string[];
@@ -19,4 +26,4 @@ export declare class RouteConflictError extends Error {
 }
 export declare function findPageRouteConflicts(node: Node, pages?: Map<string, string[]>, segments?: string[], root?: boolean): RouteConflict[];
 export declare function getRouteId(directory: string, projectRoot: string): string;
-export declare function generate(node: Node, root?: boolean, projectRoot?: string): GeneratedRoutes;
+export declare function generate(node: Node, root?: boolean, projectRoot?: string, options?: GenerateOptions): GeneratedRoutes;

package/dist/index.d.ts

@@ -1,14 +1,40 @@
 import type { Plugin } from "vite";
+import { type RouteWarning, type RouteWarningKind } from "./devtools";
 import { type RouteConventions } from "./scanner";
 export type RoutesOptions = {
     directory?: string;
     conventions?: RouteConventions;
     /**
      * Where to write the generated route type declarations, relative to the Vite
-     * project root. Set to `false` to skip writing them.
-     * @default "src/route-types.d.ts"
+     * project root.
+     *
+     * - `"auto"` writes `src/route-types.d.ts`, but only when the project root
+     *   has a `tsconfig.json` or `jsconfig.json`, so JavaScript projects without
+     *   one get no extra file.
+     * - A path ending in `.d.ts` always writes to that path.
+     * - `false` never writes the file.
+     * @default "auto"
      */
-    dts?: string | false;
+    dts?: "auto" | string | false;
+    /**
+     * What to do with route warnings during `vite build`: a loader, action, or
+     * middleware with no error file at or above it, no root not-found page, or
+     * a data module missing its expected export.
+     *
+     * - `"warn"` prints them as Vite warnings.
+     * - `"error"` fails the build, for example in CI.
+     * - `false` turns them off.
+     * - An object sets the `level` and lists warning kinds to `ignore`.
+     * @default "warn"
+     */
+    warnings?: RouteWarningsOption;
+};
+export type RouteWarningsOption = "warn" | "error" | false | {
+    level?: "warn" | "error";
+    ignore?: RouteWarningKind[];
 };
+export type { RouteWarning, RouteWarningKind } from "./devtools";
 export type { RouteConventions, RouteFileKind, RouteManifestNode, } from "./scanner";
+/** Formats route warnings for the terminal, grouped by route. */
+export declare function formatRouteWarnings(warnings: RouteWarning[]): string;
 export declare function routes(input?: string | RoutesOptions): Plugin;