From 4a50173ac23598d4d6a9ffb3c7dfb2e599c8dd86 Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 18:19:46 +0200
Subject: [PATCH 01/11] add notes about route and component preloading

---
 src/routes/guides/routing-and-navigation.mdx  |  6 ++---
 .../solid-router/advanced-concepts/data.json  |  2 +-
 .../advanced-concepts/preloading.mdx          | 22 +++++++++++++++++
 .../primitives/use-preload-route.mdx          | 24 +++++++++++++++++--
 4 files changed, 47 insertions(+), 7 deletions(-)
 create mode 100644 src/routes/solid-router/advanced-concepts/preloading.mdx

diff --git a/src/routes/guides/routing-and-navigation.mdx b/src/routes/guides/routing-and-navigation.mdx
index afaedc388..4d940b8f2 100644
--- a/src/routes/guides/routing-and-navigation.mdx
+++ b/src/routes/guides/routing-and-navigation.mdx
@@ -446,8 +446,7 @@ The preload function is then passed in the `<Route>` definition:
 You can export preload functions and data wrappers that correspond to routes from a dedicated `[route].data.js` or `[route].data.ts` file.
 This pattern provides a way to import the data function without loading anything else.
 
-```jsx
-// src/pages/users/[id].data.js
+```tsx title="src/pages/users/[id].data.js"
 import { query } from "@solidjs/router";
 
 export const getUser = query(async (id) => {
@@ -494,8 +493,7 @@ render(
 `[id].jsx` contains the component that gets rendered.
 When you wrap the function within [`createAsync`](/solid-router/reference/data-apis/create-async) with the imported function, it will yield [a signal](/routes/concepts/signals) once the anticipated promise resolves.
 
-```jsx
-// [id].jsx
+```tsx title="[id].tsx"
 import { createAsync } from "@solidjs/router";
 import { getUser } from "./[id].data";
 
diff --git a/src/routes/solid-router/advanced-concepts/data.json b/src/routes/solid-router/advanced-concepts/data.json
index 0f6e6c5f8..523931f31 100644
--- a/src/routes/solid-router/advanced-concepts/data.json
+++ b/src/routes/solid-router/advanced-concepts/data.json
@@ -1,4 +1,4 @@
 {
 	"title": "Advanced concepts",
-	"pages": ["lazy-loading.mdx"]
+	"pages": ["preloading.mdx", "lazy-loading.mdx"]
 }
diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
new file mode 100644
index 000000000..959b4236a
--- /dev/null
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -0,0 +1,22 @@
+---
+title: Preloading
+---
+
+When using the [`<A>`](/solid-router/reference/components/a) component from Solid Router, routes are preloaded by default on link hover/focus to improve perceived performance.
+
+To enhance preloading, you can define the `preload` function on your route definition.
+When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to fetch data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
+
+| user action | route behavior                          |
+| ----------- | -------------------------------------- |
+| hover   | with a 300ms delay to avoid excessive preloading  |
+| focus   | immediately                           |
+
+## Imperative Preloading
+
+You can also use the [`usePreloadRoute`](/solid-router/references/use-preload-route) helper to preload routes programmatically in response to events other than link hover/focus, such as button clicks or timers.
+This helper will load only the route's component by default, but it can receive a configuration object to also load the data.
+
+## Preloading and Lazy Loading
+
+When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/references/use-preload-route) helper in the parent component to load them when needed.
\ No newline at end of file
diff --git a/src/routes/solid-router/reference/primitives/use-preload-route.mdx b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
index 8534db781..6fe170991 100644
--- a/src/routes/solid-router/reference/primitives/use-preload-route.mdx
+++ b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
@@ -2,10 +2,30 @@
 title: usePreloadRoute
 ---
 
-`usePreloadRoute` returns a function that can be used to preload a route manually. This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API.
+`usePreloadRoute` returns a function that can be used to preload a route manually.
 
-```js
+```ts
 const preload = usePreloadRoute();
 
 preload(`/users/settings`, { preloadData: true });
 ```
+
+## Usage
+
+Routes are preloaded by default when using the [`<A>`](/solid-router/reference/components/a)` component.
+This helper is useful when you want to preload a route in response to some other event, such as a button click or a timer.
+
+## Type Signature
+
+### Parameters
+
+| Parameter | Type     | Required | Description                          |
+| --------- | -------- | -------- | ------------------------------------ |
+| `to`      | `To`     | Yes      | The route path to preload            |
+| `options` | `object` | No       | Configuration options for preloading |
+
+### Options
+
+| Option        | Type      | Default | Description                                                         |
+| ------------- | --------- | ------- | ------------------------------------------------------------------- |
+| `preloadData` | `boolean` | `false` | Whether to preload the route's data in addition to the route itself |

From 50d0a0c34dd23766983513234ae77d5ac120b1fa Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 18:35:18 +0200
Subject: [PATCH 02/11] fix backtick typo

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .../solid-router/reference/primitives/use-preload-route.mdx     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/solid-router/reference/primitives/use-preload-route.mdx b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
index 6fe170991..cd7d880ec 100644
--- a/src/routes/solid-router/reference/primitives/use-preload-route.mdx
+++ b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
@@ -12,7 +12,7 @@ preload(`/users/settings`, { preloadData: true });
 
 ## Usage
 
-Routes are preloaded by default when using the [`<A>`](/solid-router/reference/components/a)` component.
+Routes are preloaded by default when using the [`<A>`](/solid-router/reference/components/a) component.
 This helper is useful when you want to preload a route in response to some other event, such as a button click or a timer.
 
 ## Type Signature

From a2ab4635b02ac5dc4f4a268ab03d7afa81a399ec Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 18:35:35 +0200
Subject: [PATCH 03/11] fix bad URL

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 src/routes/solid-router/advanced-concepts/preloading.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index 959b4236a..46e52906d 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -14,9 +14,9 @@ When on a [SolidStart](/solid-start) application, this function can also run on
 
 ## Imperative Preloading
 
-You can also use the [`usePreloadRoute`](/solid-router/references/use-preload-route) helper to preload routes programmatically in response to events other than link hover/focus, such as button clicks or timers.
+You can also use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper to preload routes programmatically in response to events other than link hover/focus, such as button clicks or timers.
 This helper will load only the route's component by default, but it can receive a configuration object to also load the data.
 
 ## Preloading and Lazy Loading
 
-When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/references/use-preload-route) helper in the parent component to load them when needed.
\ No newline at end of file
+When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper in the parent component to load them when needed.
\ No newline at end of file

From f364e3294510e180a96d6ec977e09f42ed48e1fd Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 18:37:31 +0200
Subject: [PATCH 04/11] "start" fetching data

---
 src/routes/solid-router/advanced-concepts/preloading.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index 46e52906d..c10262c37 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -5,7 +5,7 @@ title: Preloading
 When using the [`<A>`](/solid-router/reference/components/a) component from Solid Router, routes are preloaded by default on link hover/focus to improve perceived performance.
 
 To enhance preloading, you can define the `preload` function on your route definition.
-When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to fetch data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
+When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to start fetching data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
 
 | user action | route behavior                          |
 | ----------- | -------------------------------------- |

From a4c79c1275a8163a1e730e42ea21e67a65f540d0 Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 19:42:46 +0200
Subject: [PATCH 05/11] both `<A>` and `<a>` have the preload behavior, remove
 ambiguous sentence

---
 src/routes/solid-router/advanced-concepts/preloading.mdx        | 2 +-
 .../solid-router/reference/primitives/use-preload-route.mdx     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index c10262c37..b14cd5b10 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -2,7 +2,7 @@
 title: Preloading
 ---
 
-When using the [`<A>`](/solid-router/reference/components/a) component from Solid Router, routes are preloaded by default on link hover/focus to improve perceived performance.
+Anchors in Solid Router will preload routes by default on link hover/focus to improve perceived performance.
 
 To enhance preloading, you can define the `preload` function on your route definition.
 When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to start fetching data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
diff --git a/src/routes/solid-router/reference/primitives/use-preload-route.mdx b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
index cd7d880ec..90d843b44 100644
--- a/src/routes/solid-router/reference/primitives/use-preload-route.mdx
+++ b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
@@ -12,7 +12,7 @@ preload(`/users/settings`, { preloadData: true });
 
 ## Usage
 
-Routes are preloaded by default when using the [`<A>`](/solid-router/reference/components/a) component.
+Routes are preloaded by default within Solid Router contexts.
 This helper is useful when you want to preload a route in response to some other event, such as a button click or a timer.
 
 ## Type Signature

From 7937b09f0c7b60b24e8671483d0d613770d276be Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sun, 19 Oct 2025 18:38:40 +0200
Subject: [PATCH 06/11] more content on lazy loading and nested components

---
 src/routes/reference/component-apis/lazy.mdx  | 73 ++++++++++++++++---
 .../advanced-concepts/preloading.mdx          |  4 +-
 2 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index d6b714433..33a8362aa 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -2,24 +2,75 @@
 title: lazy
 ---
 
-```ts
+Used to lazy load components to allow for code splitting. 
+Components are not loaded until rendered. 
+
+```tsx title="app.tsx"
+import { lazy } from "solid-js"
+
+const ComponentA = lazy(() => import("./ComponentA"));
+
+function App(props: { title: string }) {
+  return (
+		<ComponentA title={props.title} />
+	)
+}
+```
+
+Lazy loaded components can be used the same as its statically imported counterpart, receiving props etc. 
+Lazy components trigger `<Suspense>`
+
+## Preloading data in Nested Lazy Components
+
+Top-level lazy components will automatically be preloaded as well as their preload functions.
+Though nested lazy components will not be preloaded automatically because they are not part of the route hyerarchy.
+To preload such components, you can use the `preload` method exposed on the lazy component
+
+```tsx title="component-with-preload.tsx"
 import { lazy } from "solid-js"
 import type { Component } from "solid-js"
 
+const Nested = lazy(() => import("./Nested"))
+
+const ComponentWithPreload: Component = () => {
+  // preload Nested component when needed
+  async function handlePreload() {
+	await Nested.preload()
+  }
+
+  return (
+	<div>
+	  <button onClick={handlePreload}>Preload Nested Component</button>
+	  <Nested />
+	</div>
+  )
+}
+
+```
+
+## Type Signature
+
+```tsx
 function lazy<T extends Component<any>>(
 	fn: () => Promise<{ default: T }>
 ): T & { preload: () => Promise<T> }
 ```
 
-Used to lazy load components to allow for code splitting. 
-Components are not loaded until rendered. 
-Lazy loaded components can be used the same as its statically imported counterpart, receiving props etc. 
-Lazy components trigger `<Suspense>`
+### Type Parameters
 
-```tsx
-// wrap import
-const ComponentA = lazy(() => import("./ComponentA"));
+| Name | Constraint | Description |
+| ---- | ---------- | ----------- |
+| `T`  | `Component<any>` | The component type that will be lazily loaded (including its props).
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `fn` | `() => Promise<{ default: T }>` | Yes | A function that returns a dynamic import resolving to the component as the `default` export. |
+
+### Returns
+
+| Type | Description |
+| ---- | ----------- |
+| `T & { preload: () => Promise<T> }` | A renderable component compatible with `T` that also exposes a `preload()` method to eagerly load the module. |
 
-// use in JSX
-<ComponentA title={props.title} />
-```
diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index b14cd5b10..22ae307ac 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -19,4 +19,6 @@ This helper will load only the route's component by default, but it can receive
 
 ## Preloading and Lazy Loading
 
-When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper in the parent component to load them when needed.
\ No newline at end of file
+When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper in the parent component to load them when needed.
+
+To learn more about lazy loading components, see the [`lazy`](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components) documentation.
\ No newline at end of file

From e64012883a2ac325105f30beb4c093c724f35c3b Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Mon, 20 Oct 2025 10:38:04 +0200
Subject: [PATCH 07/11] fix typo

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 src/routes/reference/component-apis/lazy.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index 33a8362aa..306c24679 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -23,7 +23,7 @@ Lazy components trigger `<Suspense>`
 ## Preloading data in Nested Lazy Components
 
 Top-level lazy components will automatically be preloaded as well as their preload functions.
-Though nested lazy components will not be preloaded automatically because they are not part of the route hyerarchy.
+Though nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
 To preload such components, you can use the `preload` method exposed on the lazy component
 
 ```tsx title="component-with-preload.tsx"

From b1a0fb0773cb6d4ccf316a4ae54cc61799e325c1 Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Thu, 23 Oct 2025 09:54:14 +0200
Subject: [PATCH 08/11] clarify sentence with manually preloading

Co-authored-by: Eric L. Goldstein <3359116+mangs@users.noreply.github.com>
---
 src/routes/reference/component-apis/lazy.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index 306c24679..ffd214620 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -3,7 +3,7 @@ title: lazy
 ---
 
 Used to lazy load components to allow for code splitting. 
-Components are not loaded until rendered. 
+Components are not loaded until rendered or manually preloaded. 
 
 ```tsx title="app.tsx"
 import { lazy } from "solid-js"

From 4b4f2e382d9dc810e938c16ab154eb6d8de0e391 Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Thu, 23 Oct 2025 09:54:31 +0200
Subject: [PATCH 09/11] better English :)

Co-authored-by: Eric L. Goldstein <3359116+mangs@users.noreply.github.com>
---
 src/routes/reference/component-apis/lazy.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index ffd214620..d7d3d4d95 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -23,7 +23,7 @@ Lazy components trigger `<Suspense>`
 ## Preloading data in Nested Lazy Components
 
 Top-level lazy components will automatically be preloaded as well as their preload functions.
-Though nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
+However, nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
 To preload such components, you can use the `preload` method exposed on the lazy component
 
 ```tsx title="component-with-preload.tsx"

From 143ba25626ea02dc71d2cf56018ed9c3d600871a Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Thu, 23 Oct 2025 09:54:51 +0200
Subject: [PATCH 10/11] typo :)

Co-authored-by: Eric L. Goldstein <3359116+mangs@users.noreply.github.com>
---
 src/routes/reference/component-apis/lazy.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index d7d3d4d95..09babbc3a 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -24,7 +24,7 @@ Lazy components trigger `<Suspense>`
 
 Top-level lazy components will automatically be preloaded as well as their preload functions.
 However, nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
-To preload such components, you can use the `preload` method exposed on the lazy component
+To preload such components, you can use the `preload` method exposed on the lazy component.
 
 ```tsx title="component-with-preload.tsx"
 import { lazy } from "solid-js"

From 4be0415189b42353baef6fc7793c6a7671a31a9b Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sun, 26 Oct 2025 20:15:11 +0100
Subject: [PATCH 11/11] Update
 src/routes/solid-router/advanced-concepts/preloading.mdx

Co-authored-by: Eric L. Goldstein <3359116+mangs@users.noreply.github.com>
---
 src/routes/solid-router/advanced-concepts/preloading.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index 22ae307ac..0934dda06 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -19,6 +19,6 @@ This helper will load only the route's component by default, but it can receive
 
 ## Preloading and Lazy Loading
 
-When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper in the parent component to load them when needed.
+When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the `preload()` function returned from calling the [`lazy()`](https://docs.solidjs.com/reference/component-apis/lazy) component API.
 
 To learn more about lazy loading components, see the [`lazy`](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components) documentation.
\ No newline at end of file