Skip to content

Commit

Permalink
docs(load): clarify universal and server load (#11458)
Browse files Browse the repository at this point in the history
* docs(load): clarify universal and server load

Provide details and examples on how universal and server `load` runs, in what order, and what data gets returned.

* Update documentation/docs/20-core-concepts/20-load.md

* move code sample into "when to use which", simplify

---------

Co-authored-by: Rich Harris <hello@rich-harris.dev>
  • Loading branch information
theetrain and Rich-Harris authored Jan 9, 2024
1 parent 2f0f52d commit b440214
Showing 1 changed file with 25 additions and 1 deletion.
26 changes: 25 additions & 1 deletion documentation/docs/20-core-concepts/20-load.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,8 @@ Server `load` functions _always_ run on the server.

By default, universal `load` functions run on the server during SSR when the user first visits your page. They will then run again during hydration, reusing any responses from [fetch requests](#making-fetch-requests). All subsequent invocations of universal `load` functions happen in the browser. You can customize the behavior through [page options](page-options). If you disable [server side rendering](page-options#ssr), you'll get an SPA and universal `load` functions _always_ run on the client.

If a route contains both universal and server `load` functions, the server `load` runs first.

A `load` function is invoked at runtime, unless you [prerender](page-options#prerender) the page — in that case, it's invoked at build time.

### Input
Expand All @@ -190,7 +192,29 @@ Server `load` functions are convenient when you need to access data directly fro

Universal `load` functions are useful when you need to `fetch` data from an external API and don't need private credentials, since SvelteKit can get the data directly from the API rather than going via your server. They are also useful when you need to return something that can't be serialized, such as a Svelte component constructor.

In rare cases, you might need to use both together — for example, you might need to return an instance of a custom class that was initialised with data from your server.
In rare cases, you might need to use both together — for example, you might need to return an instance of a custom class that was initialised with data from your server. When using both, the server `load` return value is _not_ passed directly to the page, but to the universal `load` function (as the `data` property):

```js
/// file: src/routes/+page.server.js
/** @type {import('./$types').PageServerLoad} */
export async function load() {
return {
serverMessage: 'hello from server load function'
};
}
```

```js
/// file: src/routes/+page.js
// @errors: 18047
/** @type {import('./$types').PageLoad} */
export async function load({ data }) {
return {
serverMessage: data.serverMessage,
universalMessage: 'hello from universal load function'
};
}
```

## Using URL data

Expand Down

0 comments on commit b440214

Please sign in to comment.