diff --git a/src/routes/guides/routing-and-navigation.mdx b/src/routes/guides/routing-and-navigation.mdx index 9e3d8ad0d5..714b355387 100644 --- a/src/routes/guides/routing-and-navigation.mdx +++ b/src/routes/guides/routing-and-navigation.mdx @@ -461,8 +461,7 @@ The preload function is then passed in the `` 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) => { @@ -509,8 +508,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](/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/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx index 0760a518ba..e9b76fa2ea 100644 --- a/src/routes/reference/component-apis/lazy.mdx +++ b/src/routes/reference/component-apis/lazy.mdx @@ -16,24 +16,81 @@ description: >- performance. Components load on-demand and integrate with Suspense. --- -```ts +The `lazy` helper wraps a dynamic import and returns a component that loads on demand. +Lazy components accept the same props as their eager counterparts and integrate with `` boundaries. + +## Import + +```tsx import { lazy } from "solid-js" -import type { Component } from "solid-js" +``` + +## Type +```tsx function lazy>( - fn: () => Promise<{ default: T }> + fn: () => Promise<{ default: T }> ): T & { preload: () => Promise } ``` -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 `` +## Parameters + +### `fn` + +- **Type:** `() => Promise<{ default: T }>` +- **Required:** Yes + +Dynamic import that resolves to the component module, exposing the component as the `default` export. + +## Return value + +`lazy` returns a renderable component compatible with `T`. +The component exposes a `preload()` method that resolves the underlying module. + +| Property | Type | Description | +| -------- | ---- | ----------- | +| `preload` | `() => Promise` | Loads the module without rendering and returns the resolved component. | + +## Examples + +### Basic usage + +```tsx title="app.tsx" +import { lazy } from "solid-js" + +const ComponentA = lazy(() => import("./ComponentA")) + +function App(props: { title: string }) { + return +} +``` + +### Preloading nested lazy components ```tsx -// wrap import -const ComponentA = lazy(() => import("./ComponentA")); +import { lazy } from "solid-js" +import type { Component } from "solid-js" + +const Nested = lazy(() => import("./Nested")) -// use in JSX - +const ComponentWithPreload = () => { + const [showNested, setShowNested] = createSignal(false) + + return ( +
+ + + + +
+ ) +} ``` + +## See also + +- [`Suspense`](https://docs.solidjs.com/reference/component-apis/suspense) +- [Router preloading guide](/solid-router/advanced-concepts/preloading) diff --git a/src/routes/solid-router/advanced-concepts/data.json b/src/routes/solid-router/advanced-concepts/data.json index 0f6e6c5f8e..523931f31b 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 0000000000..7adb4431f9 --- /dev/null +++ b/src/routes/solid-router/advanced-concepts/preloading.mdx @@ -0,0 +1,44 @@ +--- +title: Preloading +--- + +Preloading smooths navigation by resolving route code and data before a user completes a transition. +Solid Router listens for intent signals, such as hover and focus, and primes the matching route after a short delay to balance responsiveness and network cost. +Understanding the timing and scope of this work lets you decide when to rely on the default behaviour and when to layer custom strategies. + +| user action | route behaviour | +| ----------- | --------------- | +| hover | waits roughly 20 ms before preloading | +| focus | preloads immediately | + +## How Solid Router Detects Intent + +Anchors registered with Solid Router emit hover and focus events that feed a small scheduler. +The router debounces the hover signal for 20ms to ignore incidental pointer passes while still reacting quickly to purposeful movement. +When the delay elapses, the router loads the route module and runs its preload routine so that navigation has the assets it needs when the user commits. + +Route modules can export a [`preload`](/solid-router/reference/preload-functions/preload) function that receives params, search values, and router context. +The function lets you seed caches, warm derived computations, or coordinate streaming behaviours without blocking the eventual render. + +> [!NOTE] +> SSR invokes route `preload` functions during the initial server render and resumes them on the client during hydration. +> Keep these functions pure so the hydrated client does not need to undo server work when it takes over. + +## Imperative Preloading Hooks + +Not every interaction funnels through an anchor element. +The [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) primitive exposes the same scheduling behaviour for imperative flows like flyout previews, timers, or observer driven experiences. + +This helper mirrors the router behaviour by resolving the module, optionally running the loader, and caching the result for the eventual navigation. +Empirical tuning of delay values helps you avoid excessive prefetching in dense UIs while still keeping high intent interactions snappy. + +## Coordinating Nested Lazy Components + +Nested lazy components live outside the router hierarchy, so route preloading does not automatically warm them. +The component API [`lazy()`](/reference/component-apis/lazy) exposes a `preload()` method that resolves a component without rendering it. +Calling both the route preload and the nested component preload can keep large detail panels responsive when a user hovers or focuses on the entry point. + +Balancing manual preloading requires observing real user flows so you avoid prefetching large bundles that the user never requests. +Profiling tools help you spot whether preloading reduces long tasks or simply shifts work earlier without net gains. + +To learn more about lazy loading components, see the [lazy documentation](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components). 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 b6368a6e44..202cd455f3 100644 --- a/src/routes/solid-router/reference/primitives/use-preload-route.mdx +++ b/src/routes/solid-router/reference/primitives/use-preload-route.mdx @@ -15,10 +15,30 @@ description: >- prefetching route data before navigation in your SolidJS app. --- -`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 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 + +### 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 |