[docs] rewrite load docs #7174
[docs] rewrite load docs #7174
Conversation
🦋 Changeset detectedLatest commit: 18a3370 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
documentation/docs/05-load.md
Outdated
| - you are building an SPA served from a static file server | ||
| - use both `load` functions in case you have a combination of requirements | ||
|
|
||
| ### Making fetch requests |
There was a problem hiding this comment.
@Conduitry in #7113 you mentioned you wanted some more details about the subtle difference of fetch and when to use it - this would be the section to add it to.
documentation/docs/05-load.md
Outdated
| SvelteKit tracks the dependencies of each `load` function to avoid re-running it unnecessarily during navigation. For example, a `load` function in a root `+layout.js` doesn't need to re-run when you navigate from one page to another unless it references `url` or a member of `params` that changed since the last navigation. | ||
| SvelteKit tracks the dependencies of each `load` function to avoid re-running it unnecessarily during navigation. For example, a `load` function in a root `+layout.js` doesn't need to re-run when you navigate from one page to another unless it references `url` or a member of `params` that changed since the last navigation. `load` functions also take into account parent `load` functions, if you reference them through `await parent()` - in this case, if an upper `load` function is rerun, so is the `load` function that does `await parent()`. | ||
|
|
||
| `load` functions do not only run when you navigate, they can also be triggered to rerun by `invalidate` or `invalidateAll` (which we get to in the next paragraph). `invalidate` is closely connected to `fetch` and `depends`, which are both methods passed to `load`. Making a `fetch` request automatically registers the fetched URL as a dependency of the load function. `depends` does the same in a manual way and registers the specified URL as a dependency. You can then use `invalidate` and pass one of the registered URLs (or a function, if you need to decide based on a pattern rather than the full URL) to it to rerun the `load` function: |
There was a problem hiding this comment.
About depends. It took a while this morning for me to figure out that you call depends in the load you are depending on, not elsewhere (like a load further down the tree.) Maybe this was just because it was my first time using it. I'm fine with the word depends now, but maybe we can point out that it means (AFIACT) "define a cache key for this load function."
Co-authored-by: Geoff Rich <4992896+geoffrich@users.noreply.github.com> Co-authored-by: Chris Carson <chris@nowzoo.com>
|
Cannot for the life of me figure out why this is failing to deploy. Builds fine locally |
|
Ah, I tell a lie. Running |
|
This is good stuff, but I can't shake the feeling that it doesn't belong in reference docs. It's a guide. Maybe we should move it to learn.svelte.dev? |
|
For me learn.svelte.dev is the place for
For me this is not a guide in that sense. What I envision for kit.svelte.dev to have is
One thing that I noticed from lurking in the questions channel on Discord is that people have a hard time to understand how to actually use the parts we give them together, and this rewrite tries to answer that for the load function. API or pure reference docs can't solve that, the tutorial can't either because it does things piece by piece instead of giving an overview in one reading, which is why I think a middle ground between tutorial and API docs is needed. The routing docs for example do this nicely because they clearly show the use case and how things fit together. I tried something similar with these docs. Previously the pieces on that page were too disconnected to make sense of them as a whole. |
|
Fair enough — in that case we should probably start thinking about what a better API section would look like. I have some edits locally (since the GitHub UI is a bad place to make prose edits), will push them up tomorrow |
|
|
||
| Be careful not to introduce accidental waterfalls when using `await parent()`. If for example you only want to merge parent data into the returned output, call it _after_ fetching your other data. | ||
| ### Cookies and headers |
There was a problem hiding this comment.
What was the reason to switch explaining headers and cookies around in this section? My arguments for headers then cookies are:
- cookies is a special case of headers
- that "you cannot set cookies in setHeaders use this instead" reads more naturally in that order
There was a problem hiding this comment.
Basically that cookies aren't just a special case of headers — cookies.set(...) causes a set-cookie header to be appended, but it also updates the cookie store that accompanies the RequestEvent. Meanwhile cookies.get(...) is nothing to do with response.headers, it reads from request.headers and the event's cookie store. Headers are the mechanism for dealing with cookies, but I think it's helpful to treat them as somewhat conceptually different — most headers just affect the response, but set-cookie affects the user agent.
In general I think it's good to be able to refer back to things that were previously covered, so that you're layering knowledge. Otherwise someone reads about setHeader, thinks 'great, I can use this to set a cookie', then learns that actually no, they have to learn this whole other thing.
Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com>
Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com>
Superseedes #7087
Closes #7148
This rewrites the load docs in a way that is more grouped around use cases and problems you want to solve. It also adds API docs for the
loadfunctions.While I was at it, I also added a link checker to check for broken links, which promptly found some outdated links which I also udpated.
Please don't delete this checklist! Before submitting the PR, please make sure you do the following:
Tests
pnpm testand lint the project withpnpm lintandpnpm checkChangesets
pnpm changesetand following the prompts. All changesets should bepatchuntil SvelteKit 1.0