diff --git a/src/routes/guides/routing-and-navigation.mdx b/src/routes/guides/routing-and-navigation.mdx index 9e3d8ad0d..714b35538 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 0760a518b..eba987616 100644 --- a/src/routes/reference/component-apis/lazy.mdx +++ b/src/routes/reference/component-apis/lazy.mdx @@ -16,24 +16,75 @@ description: >- performance. Components load on-demand and integrate with Suspense. --- -```ts +Used to lazy load components to allow for code splitting. +Components are not loaded until rendered or manually preloaded. + +```tsx title="app.tsx" +import { lazy } from "solid-js" + +const ComponentA = lazy(() => import("./ComponentA")); + +function App(props: { title: string }) { + return ( + + ) +} +``` + +Lazy loaded components can be used the same as its statically imported counterpart, receiving props etc. +Lazy components trigger `` + +## Preloading data in Nested Lazy Components + +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. + +```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 ( +
+ + +
+ ) +} + +``` + +## Type Signature + +```tsx function lazy>( 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 `` +### Type Parameters -```tsx -// wrap import -const ComponentA = lazy(() => import("./ComponentA")); +| Name | Constraint | Description | +| ---- | ---------- | ----------- | +| `T` | `Component` | 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 }` | A renderable component compatible with `T` that also exposes a `preload()` method to eagerly load the module. | -// use in JSX - -``` 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..0934dda06 --- /dev/null +++ b/src/routes/solid-router/advanced-concepts/preloading.mdx @@ -0,0 +1,24 @@ +--- +title: Preloading +--- + +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. + +| 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/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 `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 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 b6368a6e4..202cd455f 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 |