docs: state management

[dummdidumm]

• docs about state management
• more helpful error message when trying to run a SvelteKit store on the server

closes #8524

The docs are WIP, I'd like to add more stuff to it.

• maybe move the explanation about cookies from Loading Data in there?
• touch on invalidation as a method to handle state
• in general a bit more indepth about the global gotchas, maybe more code examples?
• other thoughts?

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• [x] It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• [x] This message body should clearly illustrate what problems it solves.
• [ ] Ideally, include a test that fails without this PR but passes with it.

Tests

• [ ] Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

• [ ] If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 978ac41f4ab0a7d8bd983ef98929a3fb3be5d35c

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

[Rich-Harris]

Agree that we should clarify why you can't subscribe to app stores outside component initialization (though the improved error messages are the real win here), but I do think we should be careful about how far into the weeds we go. For example the 'types of state' section feels a bit intimidating ("I need to understand all these different kinds of things? I just wanted to load some data") and yet is arguably incomplete (it doesn't mention stores, or how API/backend relates to page data).

There's a cost to adding documentation — it makes it harder for a newcomer to RTFM — and so we need to be sure that we're solving a real problem. #8524 is painfully vague about our docs' shortcomings, to the point that I'm not sure any PR could claim to close it.

[benmccann]

I agree the docs in this PR are too broad. It seems like the thing that people trip over a lot is how to use stores with SSR. I think we could cover that much more concisely. Perhaps we could document the pattern Rich recommended in https://github.com/sveltejs/kit/issues/7105#issuecomment-1305856190 in the load docs or something

[dummdidumm]

I'm good with removing the broader section, it was intended as a start to a more full-fledged docs page - imagine about twice the content there is now in the end. But I don't have a good vision of how it all could look like.

We already have a short section on stores and SSR in the load docs, which noone reads because noone thinks that it's hidden in there. I think a general "State Management" page makes sense since it's a widely used term so people are far more likely to click on that to see how things are done "the SvelteKit way".

#8614 is a prime example that we need a dedicated section for this.

[stephane-vanraes]

Perhaps the docs should simple focus on the "API" instead. And in addition you make a guides segment that goes a bit deeper in certain parts like state management. NextJS has for example a more in detail section on how to make forms https://nextjs.org/docs/guides/building-forms Remix also has a "Guides" section in their docs that cover things like data loading in more detail.

[dummdidumm]

I update the doc to remove that "types of state" prelude and added a section on form interaction instead. It has reminiscents of a trouble shooting or "do it this way instead" which I think is a good addition.

[dummdidumm]

I was debating this myself, there's duplication to the form actions section, but if you browse the docs just from looking at the titles, you may end up here searching for the best way to do this. It's a little like the error docs which also contain references to various other places in the docs.

[dummdidumm]

I moved most of the details around form actions to its respective docs page, but kept a reference to it so it's more discoverable. I also added a short URL section.

[Rich-Harris]

#9239