@solidjs/router 1.0.0-next.9 → 2.0.0-next.12

package/README.md

@@ -29,12 +29,14 @@ Explore the official [documentation](https://docs.solidjs.com/solid-router) for
 - [The Mental Model: Instance vs Hooks](#the-mental-model-instance-vs-hooks)
 - [Route Definitions](#route-definitions)
   - [Dynamic Routes](#dynamic-routes)
+  - [Typed Route Params](#typed-route-params)
   - [Match Filters](#match-filters)
   - [Optional Parameters](#optional-parameters)
   - [Wildcard Routes](#wildcard-routes)
   - [Multiple Paths](#multiple-paths)
   - [Nested Routes](#nested-routes)
   - [Lazy Route Subtrees](#lazy-route-subtrees)
+  - [File-System Routes](#file-system-routes)
 - [Typed Paths](#typed-paths)
 - [Links](#links)
 - [Preload Functions](#preload-functions)
@@ -94,6 +96,8 @@ export const adminRoutes = defineRoutes([
 export const Router = createRouter({ routes: [...appRoutes, ...adminRoutes] });
 ```
 
+Its single-route sibling `defineRoute` also types `params` inside the route's own `component` and `preload` — see [Typed Route Params](#typed-route-params).
+
 Mount it by rendering the instance. The render-prop child is your root layout — it always stays mounted, receives the matched content as `props.children`, and is the ideal place for top-level navigation and context providers:
 
 ```tsx
@@ -188,6 +192,48 @@ As long as the URL fits the pattern, the `User` component shows, and `id` is ava
 </Show>
 ```
 
+### Typed Route Params
+
+By default `params` is an open record — every key is `string | undefined`, even when the pattern guarantees it. Wrap a route in `defineRoute` and its `component` and `preload` are typed from the route's own `path`:
+
+```tsx
+import { defineRoute } from "@solidjs/router";
+
+const story = defineRoute({
+  path: "/stories/:id/:tab?",
+  preload: ({ params }) => getStory(params.id), // params.id: string
+  component: props => (
+    <Story
+      id={props.params.id}    // string — the pattern guarantees it
+      tab={props.params.tab}  // string | undefined — optional param
+    />
+  )
+});
+```
+
+`defineRoute` is an identity function at runtime — the route object drops into `routes` (or a parent's `children`) like any plain object, and `path`, `children`, `matchFilters`, and `search` still flow into `paths` and the typed hooks. Params inherited from parent routes stay accessible as `string | undefined`; nested `children` type their own params only if they use `defineRoute` themselves.
+
+For components declared away from their route, `RouteProps` takes a path witness — the same `paths` node you navigate with (`import type` keeps the instance out of the runtime graph, so no cycle) — plus an optional data type:
+
+```tsx
+import type { RouteComponent, RouteProps } from "@solidjs/router";
+import type { Router } from "./app/router";
+
+function Story(props: RouteProps<typeof Router.paths.stories, StoryData>) {
+  props.params.id; // string
+}
+
+// component-type form — props infer contextually
+const Story: RouteComponent<typeof Router.paths.stories, StoryData> = props => (
+  <h1>{props.params.id}</h1>
+);
+
+// or, anywhere under the route:
+const params = useParams(paths.stories); // typed from the tree
+```
+
+When no instance is in scope at the definition site — most notably [file-system route files](#file-system-routes), where the pattern lives in the filename — the witness can be the pattern string itself: `RouteProps<"/stories/:id">`.
+
 ### Match Filters
 
 Each parameter can be validated with a `MatchFilter` — an enum array, a regex, or a predicate. If validation fails, the route doesn't match:
@@ -316,6 +362,37 @@ The import only fires when something needs the subtree — hovering a link into
 
 Resolution is cached per thunk and append-only: the tree never changes shape after a subtree lands, it just gets more specific. Keep thunks deterministic — `() => import(...)` — rather than switching tables on runtime state.
 
+### File-System Routes
+
+The `@solidjs/router/fs` adapter turns a `file-routes` manifest into route definitions — the app imports the virtual module, the adapter maps it:
+
+```tsx
+import { pageRoutes } from "virtual:file-routes";
+import { fileRoutes } from "@solidjs/router/fs";
+
+export const Router = createRouter({ routes: fileRoutes(pageRoutes) });
+```
+
+Route files export their component as `default` and everything else as a `route` config export, which is spread into the definition. Inside a route file the pattern lives in the filename, so there's no `paths` node to witness with at the definition site — `defineFileRoute` takes the pattern string instead, types `preload`'s params from it, and validates `matchFilters` along the way. The config then doubles as the component's [`RouteProps`](#typed-route-params) witness, typing `params` from the pattern and `data` from the `preload`'s return type:
+
+```tsx
+// routes/blog/[id].tsx
+import { int } from "@solidjs/router";
+import { defineFileRoute } from "@solidjs/router/fs";
+
+export const route = defineFileRoute("/blog/:id", {
+  matchFilters: { id: int },
+  preload: ({ params }) => getPost(params.id) // params.id: string
+});
+
+export default function Post(props: RouteProps<typeof route>) {
+  props.params.id; // string
+  props.data;      // ReturnType of the preload above
+}
+```
+
+The pattern string is a typing witness — at runtime the manifest's path (from the filename) is the source of truth. With the plugin's `types` option generating a literal declaration for the virtual module, the file paths flow into `paths` and the typed hooks like a hand-written tree — `paths.blog(42)` typechecks, filters and search schemas included, and `useParams(paths.blog)` works as usual anywhere under the route.
+
 ## Typed Paths
 
 `paths` is a proxy inferred from the route tree. Property access descends into static segments, calls bind params, and it mirrors URL anatomy — params, then a search object, then a hash string:
@@ -598,9 +675,11 @@ Retrieves a reactive, store-like object of the current route's path parameters.
 
 ```tsx
 const params = useParams();            // Params (strings)
-const params = useParams(paths.users); // { id: number } — typed via matchFilters
+const params = useParams(paths.users); // { id: string } — typed from the tree
 ```
 
+Inside a route's own `component`/`preload`, [`defineRoute`](#typed-route-params) types `props.params` without a witness.
+
 ### useNavigate
 
 Retrieves a method to navigate. Accepts a string or a typed path node, plus options:
@@ -641,11 +720,14 @@ return <div classList={{ "grey-out": isRouting() }}>...</div>;
 
 ### useMatch
 
-Tests a path *pattern you supply* against the current location; returns a memo of match information or `undefined`. It never consults the route tree — the pattern doesn't have to correspond to a defined route:
+Tests a path *pattern you supply* against the current location; returns a memo of match information or `undefined`. It never consults the route tree — the pattern doesn't have to correspond to a defined route. The match's `params` are typed from the pattern, and a typed path node works too (a concrete URL — useful for "am I here" checks):
 
 ```tsx
 const match = useMatch(() => "/admin/*rest");
+match()?.params.rest; // string
 return <Show when={match()}>...</Show>;
+
+const here = useMatch(() => paths.users(2));
 ```
 
 ### useRouteMatches
@@ -654,7 +736,17 @@ Returns an accessor of the router's *resolved* matches for the current location
 
 ```tsx
 const matches = useRouteMatches();
-const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb));
+const breadcrumbs = createMemo(() => matches().map(m => m.route.info?.breadcrumb));
+```
+
+`info` is freeform by default; augment `RouteInfo` to type it app-wide — declared keys are checked at route definitions and typed on reads:
+
+```ts
+declare module "@solidjs/router" {
+  interface RouteInfo {
+    breadcrumb?: string;
+  }
+}
 ```
 
 ### usePreloadRoute
@@ -738,17 +830,18 @@ Router.match("/users/2/settings?tab=x");
 
 ## Server Integration
 
-Framework handler wiring lives in `@solidjs/router/server`. Both integrations accept the router instance directly — its routes, base, and preload are the single source of truth:
+Framework handler wiring lives in `@solidjs/router/server`. The integration accepts the router instance directly — its routes, base, and preload are the single source of truth:
 
 ```tsx
-import { createFlightDataCollector, createNoJSHandler } from "@solidjs/router/server";
+import { createFlightDataCollector } from "@solidjs/router/server";
 import { Router } from "./app/router";
 
 const collectFlightData = createFlightDataCollector(Router);
-const handleNoJS = createNoJSHandler();
 ```
 
-`createFlightDataCollector` produces the single-flight hook: after a mutation it reruns the route data the mutation invalidated for the page the client is on (or is redirected to), folding fresh data into the same response. `createNoJSHandler` implements the no-JS form convention: form posts without the client runtime redirect back with the outcome in a one-shot flash cookie that SSR reads into submission state. Both policies previously lived inside SolidStart; the router now owns them, so custom server setups get single-flight mutations and progressive enhancement without a framework.
+`createFlightDataCollector` produces the single-flight hook: after a mutation it reruns the route data the mutation invalidated for the page the client is on (or is redirected to), folding fresh data into the same response. This policy previously lived inside SolidStart; the router now owns it, so custom server setups get single-flight mutations without a framework.
+
+The no-JS form convention needs no wiring at all: the server function runtime answers form posts made without the client runtime by redirecting back with the outcome in a one-shot flash cookie, and the router's SSR reads it into submission state. To configure it (e.g. a base path), pass `createNoJSHandler(options)` from `@solidjs/web/server-functions/server` as the handler's `handleNoJS`.
 
 ## Migration from 0.x
 

package/dist/data/action.js

@@ -1,9 +1,11 @@
 import { $TRACK, action as createSolidAction, createMemo, onCleanup, getOwner } from "solid-js";
-import { isResponseEnvelope, isServer } from "@solidjs/web";
-import { createServerReference, decodeResponse, subscribeFlightData } from "@solidjs/web/server-functions";
+import { isResponseEnvelope, isServer, REVALIDATE_HEADER } from "@solidjs/web";
+import { createServerReference, decodeResponsePayload, subscribeFlightData } from "@solidjs/web/server-functions";
+// The explicit /server specifier is safe here: the only call site is
+// server-guarded, so client builds tree-shake the codec away.
+import { decodeFlashCookie } from "@solidjs/web/server-functions/server";
 import { provideFlashDecoder, provideFlightConsumer, useRouter } from "../routing.js";
 import { setRouterFormHandler } from "./events.js";
-import { decodeFlashCookie } from "./flash.js";
 import { mockBase, setFunctionName } from "../utils.js";
 import { cacheKeyOp, hashKey, revalidate, query } from "./query.js";
 const submitHooksSymbol = Symbol("routerActionSubmitHooks");
@@ -108,8 +110,12 @@ function installRouterIntegrations() {
     if (integrationsInstalled)
         return;
     integrationsInstalled = true;
-    provideFlashDecoder(decodeFlashCookie);
-    if (!isServer) {
+    if (isServer) {
+        // Server-only: initSubmissions only decodes during SSR, so client builds
+        // tree-shake the codec (which now lives behind the runtime's server entry).
+        provideFlashDecoder(decodeFlashCookie);
+    }
+    else {
         setRouterFormHandler(handleFormAction);
         provideFlightConsumer(setupFlightDataConsumer);
     }
@@ -179,14 +185,12 @@ function actionImpl(fn, options = {}) {
         finally {
             form && setFormBusy(form, -1);
         }
-        if (!response)
-            return undefined;
         let submission;
         submission = {
             input: variables,
             url,
-            result: response.data,
-            error: response.error,
+            result: response && response.data,
+            error: response && response.error,
             clear() {
                 router.submissions[1](entries => entries.filter(entry => entry !== submission));
             },
@@ -195,12 +199,20 @@ function actionImpl(fn, options = {}) {
                 return current[invokeSymbol].call({ r: router, f: form }, variables, current);
             }
         };
-        router.submissions[1](entries => [...entries, submission]);
+        // Book-keeping is intentional: only outcomes worth showing or retrying
+        // (a result or an error) enter the submissions list, so the typical void
+        // mutation leaves nothing behind. Settled hooks still see every
+        // completion — void, metadata-only, and redirects included — one
+        // `onSettled` per invocation (#580).
+        response && router.submissions[1](entries => [...entries, submission]);
         for (const hook of settledHooks.values())
             hook(submission);
-        if (response.error && !form)
-            throw response.error;
-        return response.data;
+        if (response) {
+            if (response.error && !form)
+                throw response.error;
+            return response.data;
+        }
+        return undefined;
     }
     const o = typeof options === "string" ? { name: options } : options;
     const name = o.name || (!isServer ? String(hashString(fn.toString())) : undefined);
@@ -299,11 +311,11 @@ export function setupFlightDataConsumer(router) {
  * the flight-data consumer and the action response path (which still sees
  * metadata-bearing responses when no flight data was collected).
  */
-async function applyResponseMetadata(metadata, navigate, flightData) {
+function applyResponseMetadata(metadata, navigate, flightData) {
     let keys;
     if (metadata) {
-        if (metadata.headers.has("X-Revalidate"))
-            keys = metadata.headers.get("X-Revalidate").split(",");
+        if (metadata.headers.has(REVALIDATE_HEADER))
+            keys = metadata.headers.get(REVALIDATE_HEADER).split(",");
         if (metadata.headers.has("Location")) {
             const locationUrl = metadata.headers.get("Location") || "/";
             if (locationUrl.startsWith("http")) {
@@ -319,7 +331,7 @@ async function applyResponseMetadata(metadata, navigate, flightData) {
     // set cache
     flightData && Object.keys(flightData).forEach(k => query.set(k, flightData[k]));
     // trigger revalidation
-    await revalidate(keys, false);
+    revalidate(keys, false);
 }
 async function handleResponse(response, error, navigate, metadataHandled) {
     let data;
@@ -336,14 +348,11 @@ async function handleResponse(response, error, navigate, metadataHandled) {
         // carry a codec-encoded body the router decodes itself. With the
         // flight-data consumer registered single-flight payloads never reach
         // this path, but a manually opted-in call (no consumer) still can —
-        // unwrap the standardized { value, data } shape for it too.
+        // the runtime splits its own envelope shape.
         if (response.body) {
-            data = await decodeResponse(response);
-            if (response.headers.has("X-Single-Flight")) {
-                const payload = data;
-                data = payload.value;
-                flightData = payload.data;
-            }
+            const payload = await decodeResponsePayload(response);
+            data = payload.value;
+            flightData = payload.flightData;
         }
     }
     else if (error)
@@ -354,6 +363,6 @@ async function handleResponse(response, error, navigate, metadataHandled) {
     // function's unwrapped value. Do not treat that value as a second plain
     // action response and invalidate the freshly seeded query cache again.
     if (!metadataHandled || metadata || flightData)
-        await applyResponseMetadata(metadata, navigate, flightData);
+        applyResponseMetadata(metadata, navigate, flightData);
     return data != null ? { data } : undefined;
 }

package/dist/fs.d.ts

@@ -0,0 +1,94 @@
+import type { DefinedRouteFilters, RouteParams, RoutePreloadFunc, RoutePreloadFuncArgs, RouteInfo, RouteSectionComponent, StandardSchemaV1, TypedRouteConfig, ValidFilters } from "./types.js";
+/**
+ * The type `defineFileRoute` hands back: `matchFilters` and `search` stay
+ * literal — and only present when provided precisely, which is what the
+ * `paths` machinery keys on once the manifest spreads this into the
+ * definition — while `preload` widens back to the plain contract. The
+ * pattern rides along as a phantom brand so `RouteProps<typeof route>`
+ * can type the file's component from the same witness.
+ */
+export type FileRouteConfig<S extends string = string, T = unknown, F = undefined, Sch = undefined> = TypedRouteConfig<S> & ([F] extends [undefined] ? {} : DefinedRouteFilters<S> extends F ? {} : {
+    matchFilters: F;
+}) & ([Sch] extends [undefined] ? {} : {
+    search: Sch;
+}) & {
+    preload?: RoutePreloadFunc<T>;
+    info?: RouteInfo;
+};
+/**
+ * Identity helper for a route file's `route` export that types `preload`'s
+ * `args.params` from a pattern witness — the file's path pattern, which the
+ * manifest (not this string) still provides at runtime:
+ *
+ * ```ts
+ * // routes/blog/[id].tsx
+ * export const route = defineFileRoute("/blog/:id", {
+ *   matchFilters: { id: int },
+ *   preload: ({ params }) => getPost(params.id) // params.id: string
+ * });
+ *
+ * export default function Post(props: RouteProps<typeof route>) {} // params *and* data typed
+ * ```
+ *
+ * `matchFilters` are validated against the pattern's params, and their
+ * types (and any `search` schema) flow through the manifest into `paths`.
+ */
+export declare function defineFileRoute<S extends string, T = unknown, const F = DefinedRouteFilters<S>, Sch extends StandardSchemaV1<any, any> | undefined = undefined>(path: S, config: {
+    matchFilters?: F & ValidFilters<F, S>;
+    preload?: (args: RoutePreloadFuncArgs<RouteParams<S>>) => T;
+    /** Standard Schema validator for this route's search params; its input type flows into the typed path proxy. */
+    search?: Sch;
+    info?: RouteInfo;
+}): FileRouteConfig<S, T, F, Sch>;
+/** A code-split module ref: delivered as a dynamic import. */
+export interface FileRouteLazyRef<M = Record<string, unknown>> {
+    src: string;
+    import(): Promise<M>;
+}
+/** An eager module ref: its picked exports are imported statically. */
+export interface FileRouteEagerRef<M = Record<string, unknown>> {
+    require(): M;
+}
+/** The shape of a nested route-manifest entry the adapter consumes. */
+export interface FileRouteEntry {
+    path: string;
+    page?: boolean;
+    $component?: FileRouteLazyRef<any> | undefined;
+    $$route?: FileRouteEagerRef<any> | undefined;
+    children?: readonly FileRouteEntry[] | undefined;
+}
+type RouteConfigOf<E> = E extends {
+    $$route: {
+        require(): {
+            route: infer R;
+        };
+    };
+} ? R : {};
+/**
+ * One manifest entry as a route definition. `children` is a required key on
+ * purpose: an optional key infers as `C | undefined`, and that union
+ * distributes `RoutePaths` into an uncallable shape.
+ */
+export type FileRouteFrom<E> = RouteConfigOf<E> & {
+    path: E extends {
+        path: infer P extends string;
+    } ? P : never;
+    component: E extends {
+        $component: object;
+    } ? RouteSectionComponent : undefined;
+    children: E extends {
+        children: infer C extends readonly FileRouteEntry[];
+    } ? FileRoutesFrom<C> : undefined;
+};
+export type FileRoutesFrom<T extends readonly FileRouteEntry[]> = {
+    [K in keyof T]: FileRouteFrom<T[K]>;
+};
+/**
+ * Converts the nested page entries of a file-system route manifest into
+ * route definitions: `$component` refs become code-split `lazy` components
+ * (their `src` doubles as the `moduleUrl` core resolves assets and islands
+ * against), and each entry's `route` config export is spread into its
+ * definition. Pass the result to `createRouter({ routes })`.
+ */
+export declare function fileRoutes<const T extends readonly FileRouteEntry[]>(entries: T): FileRoutesFrom<T>;
+export {};

package/dist/fs.js

@@ -0,0 +1,51 @@
+import { lazy } from "solid-js";
+/**
+ * Identity helper for a route file's `route` export that types `preload`'s
+ * `args.params` from a pattern witness — the file's path pattern, which the
+ * manifest (not this string) still provides at runtime:
+ *
+ * ```ts
+ * // routes/blog/[id].tsx
+ * export const route = defineFileRoute("/blog/:id", {
+ *   matchFilters: { id: int },
+ *   preload: ({ params }) => getPost(params.id) // params.id: string
+ * });
+ *
+ * export default function Post(props: RouteProps<typeof route>) {} // params *and* data typed
+ * ```
+ *
+ * `matchFilters` are validated against the pattern's params, and their
+ * types (and any `search` schema) flow through the manifest into `paths`.
+ */
+export function defineFileRoute(path, config) {
+    return config;
+}
+/**
+ * Converts the nested page entries of a file-system route manifest into
+ * route definitions: `$component` refs become code-split `lazy` components
+ * (their `src` doubles as the `moduleUrl` core resolves assets and islands
+ * against), and each entry's `route` config export is spread into its
+ * definition. Pass the result to `createRouter({ routes })`.
+ */
+export function fileRoutes(entries) {
+    const components = new Map();
+    const componentOf = (ref) => {
+        let component = components.get(ref.src);
+        if (!component) {
+            component = lazy(ref.import, ref.src);
+            components.set(ref.src, component);
+        }
+        return component;
+    };
+    const toRoute = (entry) => {
+        const config = (entry.$$route?.require().route ?? {});
+        return {
+            ...config,
+            path: entry.path,
+            component: entry.$component ? componentOf(entry.$component) : undefined,
+            info: { ...config.info, filesystem: true },
+            children: entry.children ? entry.children.map(toRoute) : undefined
+        };
+    };
+    return entries.map(toRoute);
+}

package/dist/index.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Arbitrary metadata attached to routes via `info`, surfaced through
+ * `useRouteMatches` and the instance's `match()`. Declared here — in the
+ * package entry — so apps can augment it for typed, discoverable metadata:
+ *
+ * ```ts
+ * declare module "@solidjs/router" {
+ *   interface RouteInfo {
+ *     breadcrumb?: string;
+ *   }
+ * }
+ * ```
+ *
+ * Declared keys are type-checked at route definitions and typed on reads;
+ * undeclared keys remain freeform.
+ */
+export interface RouteInfo {
+    [key: string]: any;
+}
 export * from "./routers/index.js";
 export * from "./lifecycle.js";
 export { useHref, useIsRouting, useLinkState, useLocation, useMatch, useNavigate, usePreloadRoute, useParams, useResolvedPath, useRouteMatches, useSearchParams, RouterContextObj as RouterContext } from "./routing.js";
@@ -6,4 +25,4 @@ export { mergeSearchString as _mergeSearchString } from "./utils.js";
 export { int } from "./paths.js";
 export type { RoutePaths, PathParamsOf, PathEnd, TypedMatchFilter, DefaultSearchTypes } from "./paths.js";
 export * from "./data/index.js";
-export type { Location, LocationChange, SearchParams, MatchFilter, MatchFilters, NavigateOptions, Navigator, OutputMatch, Params, PathMatch, RouteSectionProps, RoutePreloadFunc, RoutePreloadFuncArgs, RouteDefinition, RouteDescription, RouteMatch, RouterIntegration, RouterUtils, SetParams, SetSearchParams, Submission, BeforeLeaveEventArgs, TypedPath, TypedSearchPath, StandardSchemaV1 } from "./types.js";
+export type { Location, LocationChange, SearchParams, MatchFilter, MatchFilters, NavigateOptions, Navigator, OutputMatch, Params, PathMatch, RouteComponent, RouteParams, RouteProps, RouteSectionProps, RoutePreloadFunc, RoutePreloadFuncArgs, RouteDefinition, RouteDescription, RouteMatch, RouterIntegration, RouterUtils, SetParams, SetSearchParams, Submission, BeforeLeaveEventArgs, TypedPath, TypedSearchPath, StandardSchemaV1 } from "./types.js";