[Content]: Client data loading, confusing section

[klequis]

📚 Subject area/topic

Router

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

https://docs.solidjs.com/solid-start/building-your-application/data-loading#data-loading-on-the-client

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

I'm not sure I'm right here but I find this section confusing. It seem to transition from fetching data with createResource to fetching data using router features/API cache and createAsync, but the transition point isn't clear.

• If all client-side fetching is prone to waterfalls then that text should be move so it is clear that it applies to both examples.
• I think the Tanstack Query sentence could be combined with the previous paragraph, especially since the sentence ends with "this", referring to 'waterfalls'. How about:
  • "...loaded sections. To solve this, it can be valuable to introduce a hoist and cache mechanism such as Tanstack Query."
  • I don't know if Tanstack Query is a hoist and cache mechanism so that my need to be reworded.
• It is at this point, before the last two sentences above the second example that appears to be a transition to the next example, but that isn't clear to me.

I think these two sentences could be combined, they seem to be saying the same thing with different words.

• "for the example below we will be using the data in APIs in solid-router" (the 'in' before 'APIs' is extra)
• "Using some of the features of solid-router, we can create a cache for our data"
• How about
  • "You can also use features of Solid Router load data on the client. Here we create a cache for our data we use two members of its API, createAsync and cache.
  • OR
  • You can also load data on the client using Solid Router's API. Here we create a cache for our data.

Finally, since the 'caveats' section mention both preload and 'createResource' it I would assume it applies to both examples. However, "With this method" leads me to think they apply to the last example.

I would love to dig into this a do a pull request but don't have time at the moment so just putting down my thoughts. I'm happy to come back to it in a week or two if you think my points are valid.

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

No response

[devagrawal09]

It might be worth restructuring the data loading docs to look something like this

• Overview
• Data Loading using Solid resources
  • How to fetch using createResource
  • (optional) Suspense and ErrorBoundary
  • Link to createResource docs
  • Waterfall problem
• Data Loading using Solid Router
  • How to fetch using cache and createAsync
  • Addressing waterfalls with route.preload
  • Link to cache, createAsync and route docs
• Data Loading using third-party packages
  • Example - Tanstack Query
  • Addressing waterfalls again
  • Link to TSQ docs
• Data Loading always on the server
  • Use server fns with any of the above strategies to fetch on the server
  • Link to "use server" docs
  • Single flight mutations
    • Only supported by solid-router, possible to support with other libraries
• Link to advanced guide by OrJDev

Structuring like this might alleviate some of the issues brought up by @klequis.

On a slightly unrelated note, nothing in the start docs talk about actions and single flight. It's possible to add a separate entry for actions, but if data loading is gonna be split into createResource, solid-router, and tanstack-query, actions will have to be similarly split. At which point why not combine data loading and mutation on the same page?

Also, if solid-router is the recommended way to work with data within start, we might wanna start with router and put resources second.

Thoughts?

[brenelz]

@devagrawal09 To me this sounds like a good breakdown. I'm not 100% sure how people learn best with the data loading stuff. Feels like so many different approached we could take to help people learn it.

[devagrawal09]

@brenelz thanks, yeah this is uncharted territory since start might be the only framework that is so unopinionated about data fetching on its own.
We do have solid-router's opinions and it is kindof a first party citizen, but we want to make sure we highlight the flexibility of bringing third party solutions as well as building your own on top of the core primitives.
I think this structure achieves this decently well but I'm open to more ideas as well.
Or if you think this is good enough for a PR I can get started on writing a draft.

[adaptive-shield-matrix]

Data Loading always on the server

• Addressing waterfalls again -> needs to be added as well (even if it will be short), because if the backend does not load in parallel as well there still will be waterfalls

[adaptive-shield-matrix]

I would put the order

• start: on the server
• spa: solid-router
• spa: third-party
• spa/diy: createResource

[devagrawal09]

start: on the server
spa: solid-router
spa: third-party
spa/diy: createResource

This actually makes a lot of sense in terms of educating a newcomer in how to build apps with Start. My concern is - how exactly do we talk about data fetching on the server without first clarifying how to bring data from async sources into UI components? If the server section comes before router and resource, we'd be showing snippets using APIs that haven't been explained yet.
I do agree that the server data loading capability should be highlighted near the top of this document. But I am unsure on exactly how. Maybe once I have a draft it will become more clear.

Addressing waterfalls again -> needs to be added as well (even if it will be short), because if the backend does not load in parallel as well there still will be waterfalls

Can you elaborate? server data fetching is only concerned with turning the query functions into "use server", the strategies to avoid waterfalls depends on the loading strategy/apis being used (solid-router, third party, resources)

[adaptive-shield-matrix]

My suggestion add an additional Section called Data Fetching inside "Concepts" of solid-router docs

• DIY data fetching using resources in solidjs
• data fetching using solid-router as an spa
• data fetching using third-party using tanstack-query example

Add a separate Data Fetching section inside Building your application of solid start docs

• for how to do data fetching in in solid start (the recommended way)

with each of the docs pages linking to the other page.

[adaptive-shield-matrix]

"the strategies to avoid waterfalls depends on the loading strategy/apis being used"
My point is only that this has to be mentioned.
Waterfalls are still possible if you fetch in sequence even if you do it on the server.
Fetching on the server makes it possible to get the data in parallel, but this still has to be done and one has to check if it is actually the case.

[devagrawal09]

My point is only that this has to be mentioned.

Point taken

My suggestion add an additional Section called Data Fetching inside "Concepts" of solid-router docs
DIY data fetching using resources in solidjs
data fetching using solid-router as an spa
data fetching using third-party using tanstack-query example

I'm confused - you're saying that the data fetching docs in solid-router should have these three things? Or are the three things stuff that goes in the start docs, and the solid-router concepts addition is completely separate?

[adaptive-shield-matrix]

Data fetching docs in solid-router should have these three things -> check.
The solid-start docs: should reference/link the 3 ways in the solid-router docs.

[devagrawal09]

Why would solid router docs show how to fetch data using not-solid-router?

[adaptive-shield-matrix]

You are right.
There should be 3 separate pages, all linked to each other

• Using solid.js only
  https://docs.solidjs.com/guides/fetching-data
• Using solid-router
• Using solid-start