Server Action: Link to benefits from API Reference

[jsimonrichard]

📚 Subject area/topic

/solid-router/concepts/actions.mdx

📋 Page(s) affected (or suggested, for new content)

https://docs.solidjs.com/solid-router/concepts/actions

📋 Description of content that is out-of-date or incorrect

I'm not sure if this qualifies as incorrect, but it was confusing. I was trying to learn about why actions are useful---specifically, why they exist when we already have server functions---but based on this page alone it seems like there's no difference (other than being able to pass it to an action prop instead of onSubmit, and to a newbie like myself this doesn't seem that important).

Only after reading https://docs.solidjs.com/solid-router/reference/data-apis/action and watching a video did I understand that action handles redirects (for single-flight mutations) and invalidating caches (either all caches by default or by passing cache keys).

I don't know what the best change would be (or if there even needs to be one), but I thought I'd at least let you all know where there's friction.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[brenelz]

Maybe we could link to https://docs.solidjs.com/solid-router/reference/data-apis/action from https://docs.solidjs.com/solid-router/concepts/actions. Would that help?

[jsimonrichard]

Yes, that would help.

But longer term, it might be nice to include something on the concepts page to discuss why Solid Router needs to handle mutations. Currently the concepts page says:

When developing applications, it is common to need to communicate new information to the server based on user interactions. Actions are Solid Router’s solution to this problem.

It wasn't clear to me what the "problem" was until I realized that the router handles caching. Otherwise, a server function or fetch would do just fine.

[atilafassina]

I see. yes, it's covered in benefits of actions

But there isn't a clear connection the 2 entries.
The general idea is that the "Reference" pages are to explain API, so in theory if you're there you already know you want to use that API and what for, the docs will only guide you through the ergonomics of how to take out the best from it.

The "Learn" sections are to walk people through the benefits and treadoffs of different approach. This allow us to explain better API that are used together (for example, we need preload in order to explain how actions create Single-flight mutation through our caching system).

So, long-term, I think a clear connection between the routes and providing callouts where the Learn pages can compliment the Reference pages would be ideal.

Suggested action items for this issue

• Add callout to to data-apis/action referencing concepts/actions

[devagrawal09]

Just left a comment in #914 about potentially restructuring the data loading section and possibly including mutations.
While a callout to the data api docs is a decent solution, I think there should also be an explanation of how to do fetching and mutation together in the start docs, especially since single flight mutations are very much a start feature. Yes solid-router is also necessary, but it can be implemented with any routing/data library that works in start.