[Content]: Document Single-Flight Mutations + failures

📚 Subject area/topic

SolidStart Single-Flight Mutations

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

New section rquired

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

It would be useful and important to add documentation for Single-Flight Mutations. This doesn't seem to be documented anywhere. It should include:

• A description of what it is and how to use it
• An Eraser chart of how mutations actually work (look at SolidStart 1.0 release announcement for a sample)
• How to handle failures

Regarding the last point, this came up in a conversation recently in Start Team chat:

From what I understand, if the mutation (action) fails then you handle that as normal, whether by catching the error or using submission state. If one of the data fetches fail then that'll be reflected by whatever createAsync is consuming the data fetch, since SFM just inserts the promise returned by cache on the server into the cache on the client

What's also confusing is the fact that there's an Action section in the router docs however it's unclear how it's related to SFMs. It's slightly confusing that actions are described in router outside of Start as well.

I'm wondering if it's necessary to create a section describing mutations and ensure that users know how to find their way to actions? Perhaps this is a separate issue entirely? I don't see this requested/discussed in other topics so I'll pose it here for now.

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

No response

Start by reviewing the SolidStart 1.0 release announcement for its Single-Flight Mutations chart and compare it with the Solid Router documentation's Actions section. Define the new documentation section's scope around usage, mutation and data-fetch failures, and the relationship between mutations and actions. Done means the relevant concepts, failure handling, and navigation between the two documentation areas are clear.