@solidjs/router 1.0.0-next.8 → 1.0.0

package/README.md

@@ -10,683 +10,947 @@
 
 </div>
 
-**Solid Router** brings fine-grained reactivity to route navigation. Routes are config objects — the single source of truth for matching *and* types — and the router upgrades HTML's own interaction verbs instead of wrapping them: `<a href={path}>` and `<form action={action}>` carry typed, URL-addressable values on real platform elements, intercepted by delegation, decorated with a shared attribute vocabulary, and fully functional without JavaScript.
+**Solid Router** brings fine-grained reactivity to route navigation, enabling your single-page application to become multi-paged without full page reloads. Fully integrated into the SolidJS ecosystem, Solid Router provides declarative syntax with features like universal rendering and parallel data fetching for best performance.
 
 Explore the official [documentation](https://docs.solidjs.com/solid-router) for detailed guides and examples.
 
 ## Core Features
 
-- **Typed Routing**: URLs built through a typed path proxy inferred from your route config — `paths.users(2).settings` typechecks against the tree
-- **Plain Anchors**: no link component — `<a>` elements get `aria-current`, `data-active`, and `data-pending` automatically via compiler-claimed anchors
-- **Universal Rendering**: one factory for browser, hash, memory, and server rendering; history adapters are imports, so unused ones never enter your bundle
-- **Preload Functions**: parallel data fetching following the render-as-you-fetch pattern, triggered eagerly on link hover/focus
-- **Data APIs with Caching**: `query` and `action` with deduplication, revalidation, single-flight mutations, and progressive enhancement
-- **Typed Search Params**: opt-in per-route [Standard Schema](https://github.com/standard-schema/standard-schema) validation — `search.page` is a `number`, not `"2"`
+- **All Routing Modes**:
+  - [History-Based](https://docs.solidjs.com/solid-router/reference/components/router#router) for standard browser navigation
+  - [Hash-Based](https://docs.solidjs.com/solid-router/reference/components/hash-router#hashrouter) for navigation based on URL hash
+  - [Static Routing](https://docs.solidjs.com/solid-router/rendering-modes/ssr#server-side-rendering) for server-side rendering (_SSR_)
+  - [Memory-Based](https://docs.solidjs.com/solid-router/reference/components/memory-router#memoryrouter) for testing in non-browser environments
+- **TypeScript**: Full integration for robust, type-safe development
+- **Universal Rendering**: Seamless rendering on both client and server environments
+- **Declarative**: Define routes as components or as an object
+- **Preload Functions**: Parallel data fetching, following the render-as-you-fetch pattern
+- **Dynamic Route Parameters**: Flexible URL patterns with parameters, optional segments, and wildcards
+- **Data APIs with Caching**: Reactive data fetching with deduplication and revalidation
 
-## Table of Contents
+## Table of contents
 
 - [Getting Started](#getting-started)
-- [The Mental Model: Instance vs Hooks](#the-mental-model-instance-vs-hooks)
-- [Route Definitions](#route-definitions)
-  - [Dynamic Routes](#dynamic-routes)
-  - [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)
-- [Typed Paths](#typed-paths)
-- [Links](#links)
-- [Preload Functions](#preload-functions)
+  - [Set Up the Router](#set-up-the-router)
+  - [Configure Your Routes](#configure-your-routes)
+  - [Create Links to Your Routes](#create-links-to-your-routes)
+- [Dynamic Routes](#dynamic-routes)
+- [Nested Routes](#nested-routes)
+- [Hash Mode Router](#hash-mode-router)
+- [Memory Mode Router](#memory-mode-router)
 - [Data APIs](#data-apis)
-- [Typed Search Params](#typed-search-params)
-- [Router Config Reference](#router-config-reference)
+- [Config Based Routing](#config-based-routing)
+- [Components](#components)
 - [Router Primitives](#router-primitives)
-- [Other Environments](#other-environments)
-- [Server Integration](#server-integration)
-- [Migration from 0.x](#migration-from-0x)
+  - [useParams](#useparams)
+  - [useNavigate](#usenavigate)
+  - [useLocation](#uselocation)
+  - [useSearchParams](#usesearchparams)
+  - [useIsRouting](#useisrouting)
+  - [useMatch](#usematch)
+  - [useCurrentMatches](#useCurrentMatches)
+  - [useBeforeLeave](#usebeforeleave)
 - [SPAs in Deployed Environments](#spas-in-deployed-environments)
 
 ## Getting Started
 
+### Set Up the Router
+
 ```bash
 # use preferred package manager
 npm add @solidjs/router
 ```
 
-Define your routes as config objects and create the router outside JSX. The instance is the provider component, and `paths` is a typed URL builder inferred from the tree:
-
-```tsx
-// app/router.ts
-import { lazy } from "solid-js";
-import { createRouter } from "@solidjs/router";
+Install `@solidjs/router`, then start your application by rendering the router component
 
-export const Router = createRouter({
-  routes: [
-    { path: "/", component: lazy(() => import("./pages/Home")) },
-    { path: "/about", component: lazy(() => import("./pages/About")) },
-    {
-      path: "/users/:id",
-      component: lazy(() => import("./pages/User")),
-      children: [
-        { path: "/", component: lazy(() => import("./pages/UserOverview")) },
-        { path: "/settings", component: lazy(() => import("./pages/UserSettings")) }
-      ]
-    },
-    { path: "*404", component: lazy(() => import("./pages/NotFound")) }
-  ]
-});
+```jsx
+import { render } from "solid-js/web";
+import { Router } from "@solidjs/router";
 
-export const { paths } = Router;
+render(() => <Router />, document.getElementById("app"));
 ```
 
-This one module serves everything: the client renders the instance, and on the server the same instance reads its location from the request (or the configured history when there is none — SSG, tests). There is no separate "server router" and no need to export the raw route array.
+This sets up a Router that will match on the url to display the desired page
 
-When a tree is composed across files (feature subtrees), wrap the extracted arrays in `defineRoutes` — an identity function that preserves the literal types inference feeds on (a bare extracted array silently widens to `string` paths without it or `as const`) and type-checks the definitions where they're written:
+### Configure Your Routes
 
-```tsx
-// features/admin/routes.ts
-export const adminRoutes = defineRoutes([
-  { path: "/admin", component: Admin, children: [/* ... */] }
-]);
+Solid Router allows you to configure your routes using JSX:
 
-// app/router.ts
-export const Router = createRouter({ routes: [...appRoutes, ...adminRoutes] });
-```
+1. Add each route to a `<Router>` using the `Route` component, specifying a path and a component to render when the user navigates to that path.
 
-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:
+```jsx
+import { render } from "solid-js/web";
+import { Router, Route } from "@solidjs/router";
 
-```tsx
-// app/index.tsx
-import { render } from "@solidjs/web";
-import { Router } from "./router";
+import Home from "./pages/Home";
+import Users from "./pages/Users";
 
 render(
   () => (
     <Router>
-      {props => (
-        <>
-          <h1>My Site with lots of pages</h1>
-          {props.children}
-        </>
-      )}
+      <Route path="/users" component={Users} />
+      <Route path="/" component={Home} />
     </Router>
   ),
-  document.getElementById("app")!
+  document.getElementById("app")
 );
 ```
 
-Links are plain anchors. Typed path nodes coerce to strings on the attribute, and the router intercepts clicks through delegation:
+2. Provide a root level layout
+
+This will always be there and won't update on page change. It is the ideal place to put top level navigation and Context Providers
 
-```tsx
-import { paths } from "./router";
+```jsx
+import { render } from "solid-js/web";
+import { Router, Route } from "@solidjs/router";
 
-<nav>
-  <a href={paths()}>Home</a>
-  <a href={paths.about}>About</a>
-  <a href={paths.users(user.id).settings}>Settings</a>
-</nav>;
+import Home from "./pages/Home";
+import Users from "./pages/Users";
+
+const App = (props) => (
+  <>
+    <h1>My Site with lots of pages</h1>
+    {props.children}
+  </>
+);
+
+render(
+  () => (
+    <Router root={App}>
+      <Route path="/users" component={Users} />
+      <Route path="/" component={Home} />
+    </Router>
+  ),
+  document.getElementById("app")
+);
 ```
 
-## The Mental Model: Instance vs Hooks
+3. Create a catch-all route (404 page)
 
-The API splits across two surfaces, and the line between them is precise: **could two concurrent server requests give different answers? If yes, it's a hook. If no, it's on the instance.**
+We can create catch-all routes for pages not found at any nested level of the router. We use `*` and optionally the name of a parameter to retrieve the rest of the path.
 
-The instance is shared — one module-level object serving every mount, every request, every test. It is deliberately non-stateful (on the server there are many "current locations" at once), so it carries only the app's static routing vocabulary. Hooks read the live session from context.
+```jsx
+import { render } from "solid-js/web";
+import { Router, Route } from "@solidjs/router";
 
-| Instance — facts about the *app* | Hooks — facts about the *session* |
-| --- | --- |
-| `paths` — how to spell URLs | `useLocation`, `useParams` — where am I |
-| `match(url)` — how would a URL match | `useNavigate`, `usePreloadRoute` — move / warm |
-| `routes`, `config` — what exists | `useIsRouting`, `useRouteMatches`, `useSearchParams` — live state |
+import Home from "./pages/Home";
+import Users from "./pages/Users";
+import NotFound from "./pages/404";
 
-They compose as noun and verb — the instance supplies a typed URL, the hook acts on the current session:
+const App = (props) => (
+  <>
+    <h1>My Site with lots of pages</h1>
+    {props.children}
+  </>
+);
 
-```tsx
-const navigate = useNavigate();
-navigate(paths.users(2));                 // verb(noun)
+render(
+  () => (
+    <Router root={App}>
+      <Route path="/users" component={Users} />
+      <Route path="/" component={Home} />
+      <Route path="*404" component={NotFound} />
+    </Router>
+  ),
+  document.getElementById("app")
+);
+```
+
+4. Lazy-load route components
+
+This way, the `Users` and `Home` components will only be loaded if you're navigating to `/users` or `/`, respectively.
+
+```jsx
+import { lazy } from "solid-js";
+import { render } from "solid-js/web";
+import { Router, Route } from "@solidjs/router";
+
+const Users = lazy(() => import("./pages/Users"));
+const Home = lazy(() => import("./pages/Home"));
+
+const App = (props) => (
+  <>
+    <h1>My Site with lots of pages</h1>
+    {props.children}
+  </>
+);
 
-const params = useParams(paths.users);    // hook, typed by the instance
+render(
+  () => (
+    <Router root={App}>
+      <Route path="/users" component={Users} />
+      <Route path="/" component={Home} />
+    </Router>
+  ),
+  document.getElementById("app")
+);
 ```
 
-**Hooks are the default; import the router only when you need typed URLs or matching outside a render.** Components that only read their session (params, location, string-path navigation) never need the instance — which also means component files don't form import cycles with the router module that references them in its config.
+### Create Links to Your Routes
 
-## Route Definitions
+Use an anchor tag that takes you to a route:
 
-A route definition supports:
+```jsx
+import { lazy } from "solid-js";
+import { render } from "solid-js/web";
+import { Router, Route } from "@solidjs/router";
+
+const Users = lazy(() => import("./pages/Users"));
+const Home = lazy(() => import("./pages/Home"));
+
+const App = (props) => (
+  <>
+    <nav>
+      <a href="/about">About</a>
+      <a href="/">Home</a>
+    </nav>
+    <h1>My Site with lots of pages</h1>
+    {props.children}
+  </>
+);
+
+render(
+  () => (
+    <Router root={App}>
+      <Route path="/users" component={Users} />
+      <Route path="/" component={Home} />
+    </Router>
+  ),
+  document.getElementById("app")
+);
+```
 
-| key            | type                                    | description                                                        |
-| -------------- | --------------------------------------- | ------------------------------------------------------------------ |
-| `path`         | `string \| string[]`                    | Path partial for this route segment                                |
-| `component`    | `Component`                             | Component rendered for the matched segment                         |
-| `children`     | `RouteDefinition \| RouteDefinition[] \| () => Promise<...>` | Nested route definitions, or a thunk for a [lazy subtree](#lazy-route-subtrees) |
-| `preload`      | `RoutePreloadFunc`                      | Called on preload intent (hover/focus) and navigation              |
-| `matchFilters` | `MatchFilters`                          | Additional constraints for matching parameters                     |
-| `search`       | `StandardSchemaV1`                      | Search-param validator; its types flow into `paths` and hooks      |
-| `info`         | `Record<string, any>`                   | Arbitrary metadata, readable via `useRouteMatches`                 |
+## Dynamic Routes
 
-The tree is **immutable and there is one router per app** — that's what makes `paths` and the typed hooks truthful, it lets matching compile once and be shared by every mount, request, and `match()` call, and it means delegation, link state, and preloading all have a single owner. Compose large apps by spreading subtrees into the config (see `defineRoutes` above); mounting a router inside another router is not supported (nested `<Routes>` has been gone since 0.10) and warns in development. Sections whose *code* shouldn't load up front are [lazy route subtrees](#lazy-route-subtrees) — still one tree, still typed.
+If you don't know the path ahead of time, you might want to treat part of the path as a flexible parameter that is passed on to the component.
 
-### Dynamic Routes
+```jsx
+import { lazy } from "solid-js";
+import { render } from "solid-js/web";
+import { Router, Route } from "@solidjs/router";
 
-Treat part of the path as a parameter with a colon:
+const Users = lazy(() => import("./pages/Users"));
+const User = lazy(() => import("./pages/User"));
+const Home = lazy(() => import("./pages/Home"));
 
-```tsx
-const routes = defineRoutes([
-  { path: "/users", component: Users },
-  { path: "/users/:id", component: User }
-]);
+render(
+  () => (
+    <Router>
+      <Route path="/users" component={Users} />
+      <Route path="/users/:id" component={User} />
+      <Route path="/" component={Home} />
+    </Router>
+  ),
+  document.getElementById("app")
+);
 ```
 
-As long as the URL fits the pattern, the `User` component shows, and `id` is available via `useParams`.
+The colon indicates that `id` can be any string, and as long as the URL fits that pattern, the `User` component will show.
+
+You can then access that `id` from within a route component with `useParams`.
 
-**Note on Animation/Transitions**: routes that share the same path match are treated as the same route. To force a re-render, wrap your component in a keyed `<Show>`:
+**Note on Animation/Transitions**:
+Routes that share the same path match will be treated as the same route. If you want to force re-render you can wrap your component in a keyed `<Show>` like:
 
-```tsx
+```jsx
 <Show when={params.something} keyed>
   <MyComponent />
 </Show>
 ```
 
-### 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:
+Each path parameter can be validated using a `MatchFilter`.
+This allows for more complex routing descriptions than just checking the presence of a parameter.
 
-```tsx
-import { int, type MatchFilters } from "@solidjs/router";
+```jsx
+import { lazy } from "solid-js";
+import { render } from "solid-js/web";
+import { Router, Route } from "@solidjs/router";
+import type { MatchFilters } from "@solidjs/router";
+
+const User = lazy(() => import("./pages/User"));
 
 const filters: MatchFilters = {
-  parent: ["mom", "dad"],                                    // enum values
-  id: /^\d+$/,                                               // only numbers
-  withHtmlExtension: (v: string) => v.length > 5 && v.endsWith(".html")
+  parent: ["mom", "dad"], // allow enum values
+  id: /^\d+$/, // only allow numbers
+  withHtmlExtension: (v: string) => v.length > 5 && v.endsWith(".html"), // we want an `*.html` extension
 };
 
-const routes = defineRoutes([
-  { path: "/users/:parent/:id/:withHtmlExtension", component: User, matchFilters: filters }
-]);
+render(
+  () => (
+    <Router>
+      <Route
+        path="/users/:parent/:id/:withHtmlExtension"
+        component={User}
+        matchFilters={filters}
+      />
+    </Router>
+  ),
+  document.getElementById("app")
+);
 ```
 
-So `/users/mom/123/contact.html` matches, while `/users/aunt/123/contact.html` (invalid `parent`) and `/users/mom/me/contact.html` (non-numeric `id`) don't.
+Here, we have added the `matchFilters` prop. This allows us to validate the `parent`, `id` and `withHtmlExtension` parameters against the filters defined in `filters`.
+If the validation fails, the route will not match.
 
-The built-in `int` filter is *typed*: it constrains matching to integers at runtime and types the param as `number` at `paths` callsites:
+So in this example:
 
-```tsx
-{ path: "/users/:id", matchFilters: { id: int }, component: User }
+- `/users/mom/123/contact.html` would match,
+- `/users/dad/123/about.html` would match,
+- `/users/aunt/123/contact.html` would not match as `:parent` is not 'mom' or 'dad',
+- `/users/mom/me/contact.html` would not match as `:id` is not a number,
+- `/users/dad/123/contact` would not match as `:withHtmlExtension` is missing `.html`.
 
-paths.users(123);   // ok
-paths.users("abc"); // type error
-```
+---
 
 ### Optional Parameters
 
-Add a question mark to make a parameter optional:
+Parameters can be specified as optional by adding a question mark to the end of the parameter name:
 
-```tsx
+```jsx
 // Matches stories and stories/123 but not stories/123/comments
-{ path: "/stories/:id?", component: Stories }
+<Route path="/stories/:id?" component={Stories} />
 ```
 
 ### Wildcard Routes
 
-Use `*` to match any remainder of the path, optionally naming it to expose it as a parameter:
+`:param` lets you match an arbitrary name at that point in the path. You can use `*` to match any end of the path:
+
+```jsx
+// Matches any path that begins with foo, including foo/, foo/a/, foo/a/b/c
+<Route path="foo/*" component={Foo} />
+```
+
+If you want to expose the wild part of the path to the component as a parameter, you can name it:
 
-```tsx
-{ path: "foo/*", component: Foo }     // matches foo/, foo/a, foo/a/b/c
-{ path: "foo/*any", component: Foo }  // rest of the path available as params.any
+```jsx
+<Route path="foo/*any" component={Foo} />
 ```
 
-The wildcard token must be the last part of the path; `foo/*any/bar` won't create any routes.
+Note that the wildcard token must be the last part of the path; `foo/*any/bar` won't create any routes.
 
 ### Multiple Paths
 
-An array of paths lets a route stay mounted (no re-render) when switching between locations it matches:
+Routes also support defining multiple paths using an array. This allows a route to remain mounted and not rerender when switching between two or more locations that it matches:
 
-```tsx
-// Navigating from login to register does not re-render Login
-{ path: ["login", "register"], component: Login }
+```jsx
+// Navigating from login to register does not cause the Login component to re-render
+<Route path={["login", "register"]} component={Login} />
 ```
 
-### Nested Routes
+## Nested Routes
+
+The following two route definitions have the same result:
+
+```jsx
+<Route path="/users/:id" component={User} />
+```
+
+```jsx
+<Route path="/users">
+  <Route path="/:id" component={User} />
+</Route>
+```
+
+`/users/:id` renders the `<User/>` component, and `/users/` is an empty route.
+
+Only leaf Route nodes (innermost `Route` components) are given a route. If you want to make the parent its own route, you have to specify it separately:
+
+```jsx
+//This won't work the way you'd expect
+<Route path="/users" component={Users}>
+  <Route path="/:id" component={User} />
+</Route>
+
+// This works
+<Route path="/users" component={Users} />
+<Route path="/users/:id" component={User} />
+
+// This also works
+<Route path="/users">
+  <Route path="/" component={Users} />
+  <Route path="/:id" component={User} />
+</Route>
+```
 
-Only leaf nodes become routes. A parent with a `component` wraps its children, which render where the parent places `props.children`:
+You can also take advantage of nesting by using `props.children` passed to the route component.
 
-```tsx
+```jsx
 function PageWrapper(props) {
   return (
     <div>
-      <h1>We love our users!</h1>
+      <h1> We love our users! </h1>
       {props.children}
-      <a href={paths()}>Back Home</a>
+      <A href="/">Back Home</A>
     </div>
   );
 }
 
-const routes = defineRoutes([
-  {
-    path: "/users",
-    component: PageWrapper,
-    children: [
-      { path: "/", component: Users },
-      { path: "/:id", component: User }
-    ]
-  }
-]);
+<Route path="/users" component={PageWrapper}>
+  <Route path="/" component={Users} />
+  <Route path="/:id" component={User} />
+</Route>;
 ```
 
-You can nest indefinitely. In this example the only route created is `/layer1/layer2`, rendered as three nested divs:
+The routes are still configured the same, but now the route elements will appear inside the parent element where the `props.children` was declared.
+
+You can nest indefinitely - just remember that only leaf nodes will become their own routes. In this example, the only route created is `/layer1/layer2`, and it appears as three nested divs.
+
+```jsx
+<Route
+  path="/"
+  component={(props) => <div>Onion starts here {props.children}</div>}
+>
+  <Route
+    path="layer1"
+    component={(props) => <div>Another layer {props.children}</div>}
+  >
+    <Route path="layer2" component={() => <div>Innermost layer</div>} />
+  </Route>
+</Route>
+```
 
-```tsx
-{
-  path: "/",
-  component: props => <div>Onion starts here {props.children}</div>,
-  children: [{
-    path: "layer1",
-    component: props => <div>Another layer {props.children}</div>,
-    children: [{ path: "layer2", component: () => <div>Innermost layer</div> }]
-  }]
+## Preload Functions
+
+Even with smart caches it is possible that we have waterfalls both with view logic and with lazy loaded code. With preload functions, we can instead start fetching the data parallel to loading the route, so we can use the data as soon as possible. The preload function is called when the Route is loaded or eagerly when links are hovered.
+
+As its only argument, the preload function is passed an object that you can use to access route information:
+
+```js
+import { lazy } from "solid-js";
+import { Route } from "@solidjs/router";
+
+const User = lazy(() => import("./pages/users/[id].js"));
+
+// preload function
+function preloadUser({ params, location }) {
+  // do preloading
 }
+
+// Pass it in the route definition
+<Route path="/users/:id" component={User} preload={preloadUser} />;
 ```
 
-### Lazy Route Subtrees
+| key      | type                                           | description                                                                                                                                                                                                                                                                                                                                                                 |
+| -------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| params   | object                                         | The route parameters (same value as calling `useParams()` inside the route component)                                                                                                                                                                                                                                                                                       |
+| location | `{ pathname, search, hash, query, state, key}` | An object that you can use to get more information about the path (corresponds to [`useLocation()`](#uselocation))                                                                                                                                                                                                                                                          |
+| intent   | `"initial", "navigate", "native", "preload"`   | Indicates why this function is being called. <ul><li>"initial" - the route is being initially shown (ie page load)</li><li>"native" - navigate originated from the browser (eg back/forward)</li><li>"navigate" - navigate originated from the router (eg call to navigate or anchor clicked)</li><li>"preload" - not navigating, just preloading (eg link hover)</li></ul> |
 
-`children` also accepts a thunk, so a whole section's route table (not just its components) stays out of the initial bundle:
+A common pattern is to export the preload function and data wrappers that corresponds to a route in a dedicated `route.data.js` file. This way, the data function can be imported without loading anything else.
 
-```tsx
-// admin/routes.ts
-export default defineRoutes([
-  { path: "/", component: lazy(() => import("./Dashboard")) },
-  { path: "/users/:id", matchFilters: { id: int }, component: lazy(() => import("./User")) }
-]);
+```js
+import { lazy } from "solid-js";
+import { Route } from "@solidjs/router";
+import preloadUser from "./pages/users/[id].data.js";
+const User = lazy(() => import("/pages/users/[id].js"));
 
-// app.ts
-const router = createRouter({
-  routes: [
-    { path: "/", component: Home },
-    { path: "/admin", component: AdminShell, children: () => import("./admin/routes") }
-  ]
-});
+// In the Route definition
+<Route path="/users/:id" component={User} preload={preloadUser} />;
 ```
 
-The import only fires when something needs the subtree — hovering a link into it, navigating into it, or the server matching a URL beneath it. Until then the tree carries a placeholder that knows every URL under `/admin` belongs to the subtree without knowing its contents (static sibling routes still win without triggering the load). Everything folds in as if the routes were inline:
+The `preload` function's return value is passed to the page component for any intent other than `"preload"`, allowing you to initialize data or alternatively use our new Data APIs:
 
-- **Types**: TypeScript never runs the thunk — inference flows through the import's promise type, so `paths.admin.users(2)` typechecks (match filters and search schemas included) before any of the subtree's code exists client-side. The module's `default` or `routes` export is used. Only tables genuinely built at runtime (typed as plain `RouteDefinition[]`) degrade to untyped.
-- **Navigation**: the table load folds into the navigation transition — the old screen holds until the subtree (and its matched components) are ready, exactly like a `lazy()` route component.
-- **Preloading**: hover intent kicks the table load, and when it lands the preload continues into the inner routes' components and `preload` functions — one cascading warm-up from the earliest possible moment.
-- **Server**: SSR resolves matched boundaries during the render (use the streaming entry points — `renderToStream`/`renderToStringAsync` — as with any async work), and the single-flight collector resolves them before its data pass.
+## Data APIs
 
-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.
+Keep in mind that these are entirely optional, but they demonstrate the power of our preload mechanism.
 
-## Typed Paths
+### `query`
 
-`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:
+To prevent duplicate fetching and to handle refetching triggers, we provide a query API that accepts a function and returns the same function.
 
-```tsx
-paths.users(123)                          // ok — matchFilters flow into the callsite
-paths.users(2).settings                   // chainable into children
-paths.users(2, { tab: "x" }, "comments")  // "/users/2?tab=x#comments"
-paths.about()                             // zero-arg/search calls terminate to a plain string
-paths()                                   // "/" — the root
+```jsx
+const getUser = query(async (id) => {
+  return (await fetch(`/api/users/${id}`)).json();
+}, "users"); // used as the query key + serialized arguments
 ```
 
-Every node coerces via `toString`, so nodes drop straight into `href`, `navigate()`, and `redirect()` without explicit termination. Accessing a segment that doesn't exist in the tree, or binding a param with the wrong type, is a compile error.
+It is expected that the arguments to the query function are serializable.
 
-## Links
+This query accomplishes the following:
 
-There is no link component. Use `<a>`; the router intercepts same-origin clicks through delegation and manages link state through compiler-claimed anchors — correct at creation (so late mounts under `<Show>`, `<For>`, or portals are never stale) and refreshed if a dynamic `href` changes.
+1. It does deduping on the server for the lifetime of the request.
+2. It fills a preload cache in the browser which lasts 5 seconds. When a route is preloaded on hover or when preload is called when entering a route it will make sure to dedupe calls.
+3. We have a reactive refetch mechanism based on key. So we can tell routes that aren't new to retrigger on action revalidation.
+4. It will serve as a back/forward cache for browser navigation up to 5 mins. Any user based navigation or link click bypasses this cache. Revalidation or new fetch updates the cache.
 
-Behavior modifiers are attributes, so they work identically in client, server-rendered, and third-party markup:
+Using it with preload function might look like:
 
-| attribute  | description                                                                    |
-| ---------- | ------------------------------------------------------------------------------ |
-| `replace`  | Replace the history entry instead of pushing                                   |
-| `noscroll` | Turn off scrolling to the top after navigation                                 |
-| `state`    | JSON string [pushed](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) onto the history stack |
-| `preload`  | Set to `"false"` to opt this link out of hover/focus preloading                |
-| `link`     | Marks a router link when `explicitLinks` is enabled                            |
-| `target`   | Any value (e.g. `_self`) opts the anchor out of router handling                |
+```js
+import { lazy } from "solid-js";
+import { Route } from "@solidjs/router";
+import { getUser } from ... // the query function
 
-```tsx
-<a href={paths.login} replace>Log in</a>
-<a href={paths.docs} noscroll>Docs</a>
-<a href="https://example.com">External — untouched</a>
-```
+const User = lazy(() => import("./pages/users/[id].js"));
 
-Active and pending state is styled with CSS — one vocabulary for every kind of link:
+// preload function
+function preloadUser({params, location}) {
+  void getUser(params.id)
+}
 
-```css
-nav a[aria-current="page"] { font-weight: 600; }        /* exact match */
-nav a[data-active]         { color: var(--accent); }    /* exact or prefix match */
-a[data-pending]            { opacity: 0.6; }            /* target of in-flight navigation */
+// Pass it in the route definition
+<Route path="/users/:id" component={User} preload={preloadUser} />;
 ```
 
-(The root path only ever matches exactly, so `href={paths()}` doesn't light up on every page.)
-
-For component-library links that need reactive state beyond CSS, `useLinkState` is the programmatic counterpart of the attribute vocabulary:
+Inside your page component you:
 
-```tsx
-import { useLinkState } from "@solidjs/router";
+```jsx
+// pages/users/[id].js
+import { getUser } from ... // the query function
 
-function TabLink(props: { href: string; children: JSX.Element }) {
-  const link = useLinkState(() => props.href);
-  return (
-    <a href={props.href} class="tab" data-selected={link.active() || undefined}>
-      {props.children}
-    </a>
-  );
+export default function User(props) {
+  const user = createAsync(() => getUser(props.params.id));
+  return <h1>{user().name}</h1>;
 }
 ```
 
-## Preload Functions
+Cached function has a few useful methods for getting the key that are useful for invalidation.
 
-Even with smart caches, waterfalls happen when data fetching waits on view logic or lazy-loaded code. Preload functions start fetching data in parallel with loading the route — called when a route renders, and eagerly when links are hovered or focused.
+```ts
+let id = 5;
 
-```tsx
-import { lazy } from "solid-js";
+getUser.key; // returns "users"
+getUser.keyFor(id); // returns "users[5]"
+```
 
-const User = lazy(() => import("./pages/users/[id].js"));
+You can revalidate the query using the `revalidate` method or you can set `revalidate` keys on your response from your actions. If you pass the whole key it will invalidate all the entries for the query (ie "users" in the example above). You can also invalidate a single entry by using `keyFor`.
 
-function preloadUser({ params, location }) {
-  void getUser(params.id);
-}
+`query` can be defined anywhere and then used inside your components with:
 
-const routes = defineRoutes([{ path: "/users/:id", component: User, preload: preloadUser }]);
-```
+### `createAsync`
 
-The preload function receives:
+This is light wrapper over `createResource` that aims to serve as stand-in for a future primitive we intend to bring to Solid core in 2.0. It is a simpler async primitive where the function tracks like `createMemo` and it expects a promise back that it turns into a Signal. Reading it before it is ready causes Suspense/Transitions to trigger.
 
-| key      | type                                            | description                                                                                                                                                                                                                                     |
-| -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| params   | object                                          | The route parameters (same value as `useParams()` inside the route component)                                                                                                                                                                    |
-| location | `{ pathname, search, hash, query, state, key }` | Path information (corresponds to [`useLocation()`](#uselocation))                                                                                                                                                                                |
-| intent   | `"initial" \| "navigate" \| "native" \| "preload"` | Why this is being called: `initial` — first render; `navigate` — router navigation; `native` — browser back/forward; `preload` — link hover/focus, not navigating |
+```jsx
+const user = createAsync((currentValue) => getUser(params.id));
+```
 
-The factory-level `preload` option is the app-wide counterpart: it runs once per mount/request with the merged params of every match, and its result reaches the root render-prop as `props.data`.
+It also preserves `latest` field from `createResource`. Note that it will be removed in the future.
 
-## Data APIs
+```jsx
+const user = createAsync((currentValue) => getUser(params.id));
+return <h1>{user.latest.name}</h1>;
+```
 
-These are entirely optional, but they demonstrate the power of the preload mechanism.
+Using `query` in `createResource` directly won't work properly as the fetcher is not reactive and it won't invalidate properly.
 
-### `query`
+### `createAsyncStore`
 
-Wrap a fetching function to dedupe calls and participate in revalidation:
+Similar to `createAsync` except it uses a deeply reactive store. Perfect for applying fine-grained changes to large model data that updates.
+It also supports `latest` field which will be removed in the future.
 
-```tsx
-const getUser = query(async id => {
-  return (await fetch(`/api/users/${id}`)).json();
-}, "users"); // query key; arguments are serialized alongside it
+```jsx
+const todos = createAsyncStore(() => getTodos());
 ```
 
-A query:
+### `action`
+
+Actions are data mutations that can trigger invalidations and further routing. A list of prebuilt response helpers can be found below.
 
-1. Dedupes on the server for the lifetime of the request.
-2. Fills a preload cache in the browser lasting 5 seconds, so hover preloads and route entry share one fetch.
-3. Refetches reactively by key on action revalidation.
-4. Serves as a back/forward cache for browser navigation up to 5 minutes; user-initiated navigation bypasses it.
+```jsx
+import { action, revalidate, redirect } from "@solidjs/router"
 
-Consume results directly with Solid primitives — there is no router-specific async wrapper:
+// anywhere
+const myAction = action(async (data) => {
+  await doMutation(data);
+  throw redirect("/", { revalidate: getUser.keyFor(data.id) }); // throw a response to do a redirect
+});
 
-```tsx
-const user = createMemo(() => getUser(params.id));
-return <h1>{user().name}</h1>;
+// in component
+<form action={myAction} method="post" />
 
-// deeply reactive object data
-const todos = createProjection(() => getTodos(), []);
+//or
+<button type="submit" formaction={myAction}></button>
 ```
 
-Keys support targeted invalidation:
+Actions only work with post requests, so make sure to put `method="post"` on your form.
 
-```ts
-getUser.key;       // "users"
-getUser.keyFor(5); // "users[5]"
+Sometimes it might be easier to deal with typed data instead of `FormData` and adding additional hidden fields. For that reason Actions have a with method. That works similar to `bind` which applies the arguments in order.
+
+Picture an action that deletes Todo Item:
+
+```js
+const deleteTodo = action(async (formData: FormData) => {
+  const id = Number(formData.get("id"))
+  await api.deleteTodo(id)
+})
+
+<form action={deleteTodo} method="post">
+  <input type="hidden" name="id" value={todo.id} />
+  <button type="submit">Delete</button>
+</form>
 ```
 
-Revalidate with the `revalidate` export or by setting `revalidate` keys on action responses — the whole key invalidates every entry for the query, `keyFor` invalidates one.
+Instead with `with` you can write this:
 
-### `action`
+```js
+const deleteTodo = action(api.deleteTodo)
 
-A router action is *an action with a URL* — Solid's mutation primitive plus URL addressability, submission tracking, and response handling. Data helpers come from the router; response helpers (`redirect`, `reload`) come from `@solidjs/web` — they're protocol-level and work without the router:
+<form action={deleteTodo.with(todo.id)} method="post">
+  <button type="submit">Delete</button>
+</form>
+```
 
-```tsx
-import { action } from "@solidjs/router";
-import { redirect } from "@solidjs/web";
-import { paths } from "./router";
+Actions also take a second argument which can be the name or an option object with `name` and `onComplete`. `name` is used to identify SSR actions that aren't server functions (see note below). `onComplete` allows you to configure behavior when `action`s complete. Keep in mind `onComplete` does not work when JavaScript is disabled.
 
-const updateUser = action(async (form: FormData) => {
-  await db.users.update(form.get("id"), form);
-  throw redirect(paths.users(form.get("id"))); // typed paths work in redirects
-});
+#### Notes on `<form>` implementation and SSR
+
+This requires stable references as you can only serialize a string as an attribute, and across SSR they'd need to match. The solution is providing a unique name.
+
+```jsx
+const myAction = action(async (args) => {}, "my-action");
 ```
 
-```tsx
-<form action={updateUser} method="post">
-  <button>Save</button>
-</form>
+### `useAction`
 
-// or
-<button type="submit" formaction={updateUser}>Save</button>
+Instead of forms you can use actions directly by wrapping them in a `useAction` primitive. This is how we get the router context.
+
+```jsx
+// in component
+const submit = useAction(myAction);
+submit(...args);
 ```
 
-Actions only work with POST requests, so put `method="post"` on your form. Submitting forms get `aria-busy="true"` automatically while the action (including its revalidation) is in flight — the same CSS story as links:
+The outside of a form context you can use custom data instead of formData, and these helpers preserve types. However, even when used with server functions (in projects like SolidStart) this requires client side javascript and is not Progressive Enhanceable like forms are.
+
+### `useSubmission`/`useSubmissions`
 
-```css
-form[aria-busy] button { pointer-events: none; opacity: 0.6; }
+Are used to injecting the optimistic updates while actions are in flight. They either return a single Submission(latest) or all that match with an optional filter function.
+
+```jsx
+type Submission<T, U> = {
+  readonly input: T;
+  readonly result?: U;
+  readonly pending: boolean;
+  readonly url: string;
+  clear: () => void;
+  retry: () => void;
+};
+
+const submissions = useSubmissions(action, (input) => filter(input));
+const submission = useSubmission(action, (input) => filter(input));
 ```
 
-Forms work without JavaScript: a real POST, a redirect back, and the result seeded into submission state through a one-shot flash cookie. Single-flight mutations are on by default — the mutation response carries the refreshed route data in the same round trip.
+### Response Helpers
+
+These are used to communicate router navigations from query/actions, and can include invalidation hints. Generally these are thrown to not interfere the with the types and make it clear that function ends execution at that point.
 
-Delegation doesn't require the action's module on the client either. A form bound directly to a server action in a server-only module (a server component) renders a plain `action="/_server?id=...&args=..."` — a self-describing URL. On submit, the router synthesizes the invocation from it: the form data posts to that URL through the server-function transport, `.with()` arguments ride along in the query string, and submissions, `aria-busy`, redirects, revalidation, and single-flight data flow through the normal pipeline. The handler loads lazily on first such submit, so router-only bundles don't carry the data layer. The no-JS POST above remains the fallback only for clients that actually have no JavaScript. (Client-only actions — `action(fn, "name")` without `use server` — are their module's JS by definition and still require it on the client.)
+#### `redirect(path, options)`
+
+Redirects to the next route
+
+```js
+const getUser = query(() => {
+  const user = await api.getCurrentUser()
+  if (!user) throw redirect("/login");
+  return user;
+})
+```
 
-For optimistic UI, attach owner-scoped hooks to the action and use Solid's optimistic primitives for rendered state:
+#### `reload(options)`
 
-```tsx
-import { createOptimisticStore } from "solid-js";
-import { action, query } from "@solidjs/router";
+Reloads the data on the current page
 
-const getTodos = query(async () => fetchTodos(), "todos");
-const [todos, setTodos] = createOptimisticStore(() => getTodos(), []);
+```js
+const getTodo = query(async (id: number) => {
+  const todo = await fetchTodo(id);
+  return todo;
+}, "todo");
 
-const addTodo = action(async todo => {
-  await saveTodo(todo);
-  return { ok: true, todo };
-}, "add-todo").onSubmit(todo => {
-  setTodos(items => {
-    items.push({ ...todo, pending: true });
-  });
+const updateTodo = action(async (todo: Todo) => {
+  await updateTodo(todo.id, todo);
+  reload({ revalidate: getTodo.keyFor(todo.id) });
 });
 ```
 
-`onSubmit(...)` registers a listener in the current reactive owner — multiple components can register against the same action, and hooks are removed when their owner is disposed. `onSettled(...)` works the same way for observing completed submissions.
+## Config Based Routing
 
-The preferred pattern is returning values and letting the client interpret the result; thrown errors are still captured on `Submission.error` as an escape hatch.
+You don't have to use JSX to set up your routes; you can pass an array of route definitions:
 
-Actions have a `with` method (like `bind`) for typed arguments instead of hidden form fields:
+```jsx
+import { lazy } from "solid-js";
+import { render } from "solid-js/web";
+import { Router } from "@solidjs/router";
 
-```tsx
-const deleteTodo = action(api.deleteTodo);
+const routes = [
+  {
+    path: "/users",
+    component: lazy(() => import("/pages/users.js")),
+  },
+  {
+    path: "/users/:id",
+    component: lazy(() => import("/pages/users/[id].js")),
+    children: [
+      {
+        path: "/",
+        component: lazy(() => import("/pages/users/[id]/index.js")),
+      },
+      {
+        path: "/settings",
+        component: lazy(() => import("/pages/users/[id]/settings.js")),
+      },
+      {
+        path: "/*all",
+        component: lazy(() => import("/pages/users/[id]/[...all].js")),
+      },
+    ],
+  },
+  {
+    path: "/",
+    component: lazy(() => import("/pages/index.js")),
+  },
+  {
+    path: "/*all",
+    component: lazy(() => import("/pages/[...all].js")),
+  },
+];
 
-<form action={deleteTodo.with(todo.id)} method="post">
-  <button type="submit">Delete</button>
-</form>;
+render(() => <Router>{routes}</Router>, document.getElementById("app"));
 ```
 
-Since form actions serialize to string attributes that must match across SSR, actions that aren't server functions need a stable name: `action(fn, "my-action")`.
+Also you can pass a single route definition object for a single route:
 
-### `useAction`
+```jsx
+import { lazy } from "solid-js";
+import { render } from "solid-js/web";
+import { Router } from "@solidjs/router";
 
-Call an action directly instead of through a form — this is how the router context is captured. Outside a form you can pass typed data instead of `FormData`, but this requires client-side JavaScript and is not progressively enhanceable:
+const route = {
+  path: "/",
+  component: lazy(() => import("/pages/index.js")),
+};
 
-```tsx
-const submit = useAction(myAction);
-submit(...args);
+render(() => <Router>{route}</Router>, document.getElementById("app"));
 ```
 
-### `useSubmissions`
+## Alternative Routers
 
-Returns settled submission records for an action — the durable history layer, not in-flight state. Useful for reading completed results, clearing old submissions, retrying, or replaying settled errors:
+### Hash Mode Router
 
-```tsx
-const submissions = useSubmissions(action, input => filter(input));
-const latest = submissions.at(-1);
-// { input, result?, error, url, clear(), retry() }
-```
+By default, Solid Router uses `location.pathname` as route path. You can simply switch to hash mode through using `<HashRouter>`.
 
-Use Solid's `createOptimistic` / `createOptimisticStore` for in-flight UI.
+```jsx
+import { HashRouter } from "@solidjs/router";
 
-## Typed Search Params
+<HashRouter />;
+```
 
-Give a route a [Standard Schema](https://github.com/standard-schema/standard-schema) validator (Valibot, Zod, ArkType, hand-rolled…) and its types flow into `paths` and `useSearchParams`:
+### Memory Mode Router
 
-```tsx
-import * as v from "valibot";
+You can also use memory mode router for testing purpose.
 
-const routes = defineRoutes([
-  {
-    path: "/search",
-    component: Search,
-    search: v.object({
-      q: v.optional(v.string(), ""),
-      page: v.optional(v.pipe(v.unknown(), v.transform(Number)), 1)
-    })
-  }
-]);
+```jsx
+import { MemoryRouter } from "@solidjs/router";
+
+<MemoryRouter />;
 ```
 
-```tsx
-const [search, setSearch] = useSearchParams(paths.search);
-search.page;                          // number (parsed, not "2")
-setSearch({ page: search.page + 1 }); // typed setter
+### SSR Routing
+
+For SSR you can use the static router directly or the browser Router defaults to it on the server, just pass in the url.
 
-<a href={paths.search({ q: "solid", page: 2 })}>Search</a>; // typed builder
+```jsx
+import { isServer } from "solid-js/web";
+import { Router } from "@solidjs/router";
+
+<Router url={isServer ? req.url : ""} />;
 ```
 
-Without a schema, `useSearchParams()` behaves as before: raw string values, merge-on-set semantics (`''`, `undefined`, and `null` remove keys), navigation-like updates with auto-scrolling disabled.
+## Components
+
+### `<Router>`
+
+This is the main Router component for the browser.
+
+| prop          | type                                                     | description                                                                                                                                                                               |
+| ------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| children      | `JSX.Element`, `RouteDefinition`, or `RouteDefinition[]` | The route definitions                                                                                                                                                                     |
+| root          | Component                                                | Top level layout component                                                                                                                                                                |
+| base          | string                                                   | Base url to use for matching routes                                                                                                                                                       |
+| actionBase    | string                                                   | Root url for server actions, default: `/_server`                                                                                                                                          |
+| preload       | boolean                                                  | Enables/disables preloads globally, default: `true`                                                                                                                                       |
+| explicitLinks | boolean                                                  | Disables all anchors being intercepted and instead requires `<A>`. Default: `false`. (To disable interception for a specific link, set `target` to any value, e.g. `<a target="_self">`.) |
+
+### `<A>`
+
+Like the `<a>` tag but supports automatic apply of base path + relative paths and active class styling (requires client side JavaScript).
+
+The `<A>` tag has an `active` class if its href matches the current location, and `inactive` otherwise. **Note:** By default matching includes locations that are descendants (eg. href `/users` matches locations `/users` and `/users/123`), use the boolean `end` prop to prevent matching these. This is particularly useful for links to the root route `/` which would match everything.
+
+| prop          | type    | description                                                                                                                                                                              |
+| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| href          | string  | The path of the route to navigate to. This will be resolved relative to the route that the link is in, but you can preface it with `/` to refer back to the root.                        |
+| noScroll      | boolean | If true, turn off the default behavior of scrolling to the top of the new page                                                                                                           |
+| replace       | boolean | If true, don't add a new entry to the browser history. (By default, the new page will be added to the browser history, so pressing the back button will take you to the previous route.) |
+| state         | unknown | [Push this value](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) to the history stack when navigating                                                               |
+| inactiveClass | string  | The class to show when the link is inactive (when the current location doesn't match the link)                                                                                           |
+| activeClass   | string  | The class to show when the link is active                                                                                                                                                |
+| end           | boolean | If `true`, only considers the link to be active when the current location matches the `href` exactly; if `false`, check if the current location _starts with_ `href`                     |
+
+### `<Navigate />`
 
-## Router Config Reference
+Solid Router provides a `Navigate` component that works similarly to `A`, but it will _immediately_ navigate to the provided path as soon as the component is rendered. It also uses the `href` prop, but you have the additional option of passing a function to `href` that returns a path to navigate to:
 
-```tsx
-createRouter(config);
+```jsx
+function getPath({ navigate, location }) {
+  // navigate is the result of calling useNavigate(); location is the result of calling useLocation().
+  // You can use those to dynamically determine a path to navigate to
+  return "/some-path";
+}
+
+// Navigating to /redirect will redirect you to the result of getPath
+<Route path="/redirect" component={() => <Navigate href={getPath} />} />;
 ```
 
-| option          | type                       | description                                                                                            |
-| --------------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `routes`        | `RouteDefinition[]`        | The route tree — inline arrays infer literally; wrap extracted trees in `defineRoutes`                   |
-| `base`          | `string`                   | Base url to use for matching routes                                                                     |
-| `preload`       | `RoutePreloadFunc`         | App-wide preload: once per mount/request, result reaches the root render-prop as `props.data`           |
-| `history`       | `RouterHistory`            | History adapter; defaults to browser history on the client and the request URL on the server            |
-| `singleFlight`  | `boolean`                  | Single-flight mutations, default `true`                                                                 |
-| `actionBase`    | `string`                   | Root url for server actions, default `/_server`                                                         |
-| `preloadLinks`  | `boolean`                  | Preload route code/data on link hover and focus, default `true`                                         |
-| `explicitLinks` | `boolean`                  | Require the `link` attribute for router handling instead of intercepting all anchors, default `false`   |
-| `transformUrl`  | `(url: string) => string`  | Rewrite URLs before matching                                                                            |
+### `<Route>`
 
-The returned instance is the provider component and carries the static surface:
+The Component for defining Routes:
 
-| member    | description                                                                                     |
-| --------- | ------------------------------------------------------------------------------------------------ |
-| `paths`   | The [typed path proxy](#typed-paths)                                                             |
-| `match`   | Pure matching against an arbitrary URL — no rendering or request context; root→leaf, `[]` if none |
-| `routes`  | The config tree                                                                                   |
-| `config`  | The full config — lets server integrations consume the instance directly                          |
+| prop         | type               | description                                                       |
+| ------------ | ------------------ | ----------------------------------------------------------------- |
+| path         | string             | Path partial for defining the route segment                       |
+| component    | `Component`        | Component that will be rendered for the matched segment           |
+| matchFilters | `MatchFilters`     | Additional constraints for matching against the route             |
+| children     | `JSX.Element`      | Nested `<Route>` definitions                                      |
+| preload      | `RoutePreloadFunc` | Function called during preload or when the route is navigated to. |
 
 ## Router Primitives
 
-Hooks read the live session off router context.
+Solid Router provides a number of primitives that read off the Router and Route context.
 
 ### useParams
 
-Retrieves a reactive, store-like object of the current route's path parameters. Pass a paths node for typing:
+Retrieves a reactive, store-like object containing the current route path parameters as defined in the Route.
 
-```tsx
-const params = useParams();            // Params (strings)
-const params = useParams(paths.users); // { id: number } — typed via matchFilters
+```js
+const params = useParams();
+
+// fetch user based on the id path parameter
+const [user] = createResource(() => params.id, fetchUser);
 ```
 
 ### useNavigate
 
-Retrieves a method to navigate. Accepts a string or a typed path node, plus options:
+Retrieves method to do navigation. The method accepts a path to navigate to and an optional object with the following options:
+
+- resolve (_boolean_, default `true`): resolve the path against the current route
+- replace (_boolean_, default `false`): replace the history entry
+- scroll (_boolean_, default `true`): scroll to top after navigation
+- state (_any_, default `undefined`): pass custom state to `location.state`
 
-- `resolve` (_boolean_, default `true`): resolve the path against the current route
-- `replace` (_boolean_, default `false`): replace the history entry
-- `scroll` (_boolean_, default `true`): scroll to top after navigation
-- `state` (_any_): pass custom state to `location.state` (serialized with [structured clone](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm))
+**Note:** The state is serialized using the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) which does not support all object types.
 
-```tsx
+```js
 const navigate = useNavigate();
-navigate(paths.login, { replace: true });
-```
 
-For declarative redirects on render (the old `<Navigate>`), call it during component setup or redirect from a preload.
+if (unauthorized) {
+  navigate("/login", { replace: true });
+}
+```
 
 ### useLocation
 
-Retrieves the reactive `location` object:
+Retrieves reactive `location` object useful for getting things like `pathname`.
 
-```tsx
+```js
 const location = useLocation();
+
 const pathname = createMemo(() => parsePath(location.pathname));
 ```
 
 ### useSearchParams
 
-See [Typed Search Params](#typed-search-params). Reads are proxied — access properties to subscribe.
+Retrieves a tuple containing a reactive object to read the current location's query parameters and a method to update them. The object is a proxy so you must access properties to subscribe to reactive updates. Note values will be strings and property names will retain their casing.
+
+The setter method accepts an object whose entries will be merged into the current query string. Values `''`, `undefined` and `null` will remove the key from the resulting query string. Updates will behave just like a navigation and the setter accepts the same optional second parameter as `navigate` and auto-scrolling is disabled by default.
+
+```js
+const [searchParams, setSearchParams] = useSearchParams();
+
+return (
+  <div>
+    <span>Page: {searchParams.page}</span>
+    <button
+      onClick={() =>
+        setSearchParams({ page: (parseInt(searchParams.page) || 0) + 1 })
+      }
+    >
+      Next Page
+    </button>
+  </div>
+);
+```
 
 ### useIsRouting
 
-A signal indicating whether the router is processing a navigation — useful for pending UI while the next route and its data settle:
+Retrieves signal that indicates whether the route is currently in a Transition. Useful for showing stale/pending state when the route resolution is Suspended during concurrent rendering.
 
-```tsx
+```js
 const isRouting = useIsRouting();
-return <div classList={{ "grey-out": isRouting() }}>...</div>;
+
+return (
+  <div classList={{ "grey-out": isRouting() }}>
+    <MyAwesomeContent />
+  </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:
+`useMatch` takes an accessor that returns the path and creates a Memo that returns match information if the current path matches the provided path. Useful for determining if a given path matches the current route.
+
+```js
+const match = useMatch(() => props.href);
 
-```tsx
-const match = useMatch(() => "/admin/*rest");
-return <Show when={match()}>...</Show>;
+return <div classList={{ active: Boolean(match()) }} />;
 ```
 
-### useRouteMatches
+### useCurrentMatches
+
+`useCurrentMatches` returns all the matches for the current matched route. Useful for getting all the route information.
+
+For example if you stored breadcrumbs on your route definition you could retrieve them like so:
 
-Returns an accessor of the router's *resolved* matches for the current location — the chain of route definitions producing the current render, outermost first. This is the counterpart to `useMatch`: one reflects the route tree, the other tests a pattern. Useful for reading `info` metadata:
+```js
+const matches = useCurrentMatches();
 
-```tsx
-const matches = useRouteMatches();
-const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb));
+const breadcrumbs = createMemo(() =>
+  matches().map((m) => m.route.info.breadcrumb)
+);
 ```
 
 ### usePreloadRoute
 
-Returns a function to preload a route manually — the same work link hover/focus triggers automatically. Accepts strings, URLs, and typed path nodes:
+`usePreloadRoute` returns a function that can be used to preload a route manual. This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API.
 
-```tsx
+```js
 const preload = usePreloadRoute();
-preload(paths.users(2).settings, { preloadData: true });
-```
 
-### useLinkState
-
-Reactive `active`/`current`/`pending` state for [custom link components](#links).
+preload(`/users/settings`, { preloadData: true });
+```
 
 ### useBeforeLeave
 
-Takes a function called before leaving a route. The blocking machinery is installed lazily on first use, so apps that never call `useBeforeLeave` don't pay for it in their bundle. The handler receives:
+`useBeforeLeave` takes a function that will be called prior to leaving a route. The function will be called with:
 
-- `from` (_Location_): current location (before change)
-- `to` (_string | number_): path passed to `navigate`
-- `options` (_NavigateOptions_): options passed to `navigate`
-- `preventDefault()`: call to block the route change
-- `defaultPrevented` (_readonly boolean_): `true` if any previous handler called `preventDefault`
-- `retry(force?)`: retry the navigation, e.g. after confirming with the user; pass `true` to skip re-running leave handlers
+- from (_Location_): current location (before change).
+- to (_string | number_): path passed to `navigate`.
+- options (_NavigateOptions_): options passed to `navigate`.
+- preventDefault (_function_): call to block the route change.
+- defaultPrevented (_readonly boolean_): `true` if any previously called leave handlers called `preventDefault`.
+- retry (_function_, _force?: boolean_ ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (i.e. force navigate without confirming).
 
-```tsx
+Example usage:
+
+```js
 useBeforeLeave((e: BeforeLeaveEventArgs) => {
   if (form.isDirty && !e.defaultPrevented) {
+    // preventDefault to block immediately and prompt user async
     e.preventDefault();
     setTimeout(() => {
       if (window.confirm("Discard unsaved changes - are you sure?")) {
+        // user wants to proceed anyway so retry with force=true
         e.retry(true);
       }
     }, 100);
@@ -694,153 +958,73 @@ useBeforeLeave((e: BeforeLeaveEventArgs) => {
 });
 ```
 
-## Other Environments
+## Migrations from 0.9.x
 
-History adapters are plain imports, so unused ones never enter your bundle:
+v0.10.0 brings some big changes to support the future of routing including Islands/Partial Hydration hybrid solutions. Most notably there is no Context API available in non-hydrating parts of the application.
 
-```tsx
-import { createRouter, hashHistory, memoryHistory } from "@solidjs/router";
+The biggest changes are around removed APIs that need to be replaced.
 
-// hash mode
-const Router = createRouter({ routes, history: hashHistory() });
+### `<Outlet>`, `<Routes>`, `useRoutes`
 
-// tests and non-browser environments
-const Router = createRouter({ routes, history: memoryHistory("/users/1") });
-```
+This is no longer used and instead will use `props.children` passed from into the page components for outlets. This keeps the outlet directly passed from its page and avoids oddness of trying to use context across Islands boundaries. Nested `<Routes>` components inherently cause waterfalls and are `<Outlets>` themselves so they have the same concerns.
 
-### Environments without Proxy
+Keep in mind no `<Routes>` means the `<Router>` API is different. The `<Router>` acts as the `<Routes>` component and its children can only be `<Route>` components. Your top-level layout should go in the root prop of the router [as shown above](#configure-your-routes)
 
-On runtimes without `Proxy` support (some older smart TVs), the core router still works: typed `paths` are built lazily so they only require `Proxy` if you access them, and `params`/`location.query` can be swapped to a `Proxy`-free implementation through the history adapter's `paramsWrapper`/`queryWrapper` utils:
+## `element` prop removed from `Route`
 
-```tsx
-const base = browserHistory();
-const history = {
-  ...base,
-  // wrappers build objects with defined getters instead of a Proxy
-  utils: { ...base.utils, paramsWrapper, queryWrapper }
-};
-const Router = createRouter({ routes, history });
-```
+Related without Outlet component it has to be passed in manually. At which point the `element` prop has less value. Removing the second way to define route components to reduce confusion and edge cases.
 
-On the server the request URL drives rendering automatically. Without a request event (SSG scripts, server-side tests), the configured history adapter provides the location, so `memoryHistory("/page")` renders that page isomorphically.
+### `data` functions & `useRouteData`
 
-The instance also matches arbitrary URLs anywhere — server middleware, sitemap generation, tests — with no rendering involved:
-
-```tsx
-import { Router } from "./router";
-
-Router.match("/users/2/settings?tab=x");
-// [
-//   { path: "/users/:id", match: "/users/2", params: { id: "2" } },
-//   { path: "/settings", match: "/users/2/settings", params: {} }
-// ]
-```
+These have been replaced by a preload mechanism. This allows link hover preloads (as the preload function can be run as much as wanted without worry about reactivity). It support deduping/query APIs which give more control over how things are cached. It also addresses TS issues with getting the right types in the Component without `typeof` checks.
 
-## Server Integration
+That being said you can reproduce the old pattern largely by turning off preloads at the router level and then injecting your own Context:
 
-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:
-
-```tsx
-import { createFlightDataCollector, createNoJSHandler } 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.
-
-## Migration from 0.x
-
-This guide maps from the stable 0.x releases (Solid 1). 1.0 removes the component-based API — the `createRouter` factory is the only way to set up the router, and plain `<a>` elements are the only link primitive. 1.0 also targets Solid 2, so the async data patterns change alongside the router API.
-
-### Router components → `createRouter`
-
-```tsx
-// 0.x
-<Router root={App}>
-  <Route path="/users" component={Users} />
-  <Route path="/users/:id" component={User} />
-</Router>
-
-// 1.0
-const Router = createRouter({
-  routes: [
-    { path: "/users", component: Users },
-    { path: "/users/:id", component: User }
-  ]
-});
-
-<Router>{props => <App {...props} />}</Router>
-```
-
-- `<HashRouter>` → `createRouter({ routes, history: hashHistory() })`
-- `<MemoryRouter>` / `createMemoryHistory` → `createRouter({ routes, history: memoryHistory("/initial") })`
-- `<StaticRouter url>` / `<Router url>` for SSR → automatic from the request URL; without a request event, pass `memoryHistory(url)`
-- `root` prop → the render-prop child; `rootPreload` → the factory's `preload` option
-
-### JSX `<Route>` → config objects
-
-Route props map 1:1 onto definition keys (`path`, `component`, `preload`, `matchFilters`, `info`); nesting becomes `children` arrays. Wrap extracted route trees in `defineRoutes` to get typed `paths`. File-based routing generates config.
-
-### `<A>` → plain `<a>`
-
-- `<A href replace noScroll state>` → `<a href replace noscroll state>` (attributes, all lowercase)
-- `activeClass` / `inactiveClass` → CSS attribute selectors on `[data-active]` / `[aria-current="page"]`
-- `end` → style exact matches with `[aria-current="page"]` instead of `[data-active]`; the root path already only matches exactly
-- Route-relative hrefs → typed `paths`; `useResolvedPath` / `useHref` remain for manual resolution
-- Custom link components → `useLinkState`
-
-### Removed and renamed
-
-- `<Navigate>` → call `useNavigate()` during component setup, or redirect from a preload
-- `useCurrentMatches` → `useRouteMatches` (same behavior)
-- `redirect` / `reload` → import from `@solidjs/web`; they're protocol-level and work without the router
-- `json(data, init)` → `respond(data, init)` from `@solidjs/web`
-- `cache` (deprecated alias) → `query`
-
-### Data APIs (Solid 2)
+```js
+import { lazy } from "solid-js";
+import { Route } from "@solidjs/router";
 
-- `createAsync` / `createAsyncStore` are gone — read `query()` results with Solid 2 primitives: `createMemo`, `createProjection`, `createOptimistic`, `createOptimisticStore`.
+const User = lazy(() => import("./pages/users/[id].js"));
 
-```tsx
-// 0.x
-const user = createAsync(() => getUser(params.id));
+// preload function
+function preloadUser({ params, location }) {
+  const [user] = createResource(() => params.id, fetchUser);
+  return user;
+}
 
-// 1.0
-const user = createMemo(() => getUser(params.id));
+// Pass it in the route definition
+<Router preload={false}>
+  <Route path="/users/:id" component={User} preload={preloadUser} />
+</Router>;
 ```
 
-- `query()` stays the source of truth for cached reads and invalidation.
-- `useSubmission` (singular) is gone, and submissions are now settled history rather than in-flight state. Pending/optimistic UI moves to Solid's optimistic primitives fed by the action's `.onSubmit(...)` hook; read settled results with `useSubmissions()` and select the latest with `.at(-1)`.
+And then in your component taking the page props and putting them in a Context.
 
-```tsx
-// 0.x — read in-flight state off the submission
-const submitting = useSubmission(addTodo);
-<span>{submitting.pending && "Saving..."}</span>;
+```js
+function User(props) {
+  <UserContext.Provider value={props.data}>
+    {/* my component content  */}
+  </UserContext.Provider>;
+}
 
-// 1.0 — optimistic primitives own in-flight state
-const [todos, setTodos] = createOptimisticStore(() => getTodos(), []);
-const addTodo = action(saveTodo).onSubmit(todo =>
-  setTodos(items => {
-    items.push({ ...todo, pending: true });
-  })
-);
+// Somewhere else
+function UserDetails() {
+  const user = useContext(UserContext);
+  // render stuff
+}
 ```
 
-- Action lifecycle centers on instance methods: `.onSubmit(...)` for owner-scoped optimistic work, `.onSettled(...)` for observing completions. Returned values are the expected result channel; thrown errors land on `Submission.error`.
-
 ## SPAs in Deployed Environments
 
-When deploying a client-side-routed application without server-side rendering, you need to handle redirects to your index page so that loading other URLs doesn't return a 404.
+When deploying applications that use a client side router that does not rely on Server Side Rendering you need to handle redirects to your index page so that loading from other URLs does not cause your CDN or Hosting to return not found for pages that aren't actually there.
 
-On Netlify, create a `_redirects` file:
+Each provider has a different way of doing this. For example on Netlify you create a `_redirects` file that contains:
 
 ```sh
 /*   /index.html   200
 ```
 
-On Vercel, add a rewrites section to `vercel.json`:
+On Vercel you add a rewrites section to your `vercel.json`:
 
 ```json
 {