[docs] clarify and add warning for load function

[ignatiusmb]

Closes #1542

[changeset-bot]

⚠️ No Changeset found

Latest commit: 214460b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[benmccann]

I'm not sure any of this is particular to load, which makes it seem a bit odd to me to put it there. E.g. it's also true for endpoints that if you mutate a singleton that it will persist across calls. And sometimes you actually want to do that - it's how we recommend you setup a database https://kit.svelte.dev/faq#integrations

[ignatiusmb]

That's true, but most of the problems occurs in load function and since we're writing it in the #loading section, I think it should be pretty clear that the warning only applies to mutations while loading. Endpoints are a different thing (and context) since they can only run in the server and never in client.

[ignatiusmb]

I think this is really a common pitfall like what #1542 (comment) says, especially for users using plain SPA Svelte coming to SvelteKit. Newcomers aren't really aware of the underlying issue when using load and would treat it as "preparing the data of the current page for client", thus the assumption that each call was clean. One could argue that users should've read the docs more carefully, but we could also make it better and have this notes highlighted.

This is also probably why we get a lot of requests to have a separate load that can exclusively run on either server or client, and also a lot of other issues specifically relating to just the load function.

[Rich-Harris]

I realise this PR has got very involved for such a straightforward change, but this section of the docs needs some work anyway and this is as good a time as any, so I left some suggestions to that effect

[ignatiusmb]

Updated.

FYI, the locals and session bit were from #1542 (comment) which I thought might be worth mentioning, but if it creates more confusion then it's probably best not to.

[Rich-Harris]

thanks!