[doc]: recommend pairs of Apollo fetch-policy and conditionals in the render flow

[brendanfalkowski]

Describe the request
Apollo Client can be frustrating during development. We had two problems:

1. Changing our GQL API while building our frontend leads to stale responses. It's annoying clearing local storage constantly.
2. We implemented multi-store and B2B account switching, but responses weren't differentiated in Apollo's cache across stores/accounts so the wrong data would return from cache (we later figured this out).

As a workaround during dev, we started writing fetch-policy: network-only on every request and wrote our render flows with extreme simplicity:

if (loading) {
    return <Loading />;
}

if (error) {
    return <p>Error loading X info.</p>;
}

return <div>the data</div>;

Almost all of our code is written this way, but we understand that once we begin to utilize other fetch-policy values that Apollo Client has some quirks around what data/!data and loading mean when the cache is available to return data and/or network calls are in flight.

We want to run a tight ship, but it feels like bad API design if we need to have different conditionals like if (loading && !data) depending on the fetch-policy being applied. The risk of a developer copypasta-ing and not understanding the relationship between fetch-policy and render flow is easy to overlook.

As I understand it Apollo Client v3 changes how some of this will work. It would be nice if documentation contained a table of

• (left column) fetch policy
• (middle column) render flow conditionals for data/error/loading
• (right column) an explanation of that pairing or why you'd use it/not

I'd guess there are only a few patterns actually needed, and this documentation would save developers learning what/why Apollo does before they spread bad patterns around the site.

Possible solutions

A new page that links from the last section here:
https://magento.github.io/pwa-studio/technologies/basic-concepts/client-side-caching/

Screenshots
If applicable, add screenshots to help explain the problem.

Please let us know whether this is a new topic or a topic change request:

• New Topic Request (ie. missing entire topic/section)
• Topic Change Request (ie. spelling, organization)

[m2-assistant]

Hi @brendanfalkowski. Thank you for your report.
To help us process this issue please make sure that you provided sufficient information.

Please, add a comment to assign the issue: @magento I am working on this

---

• Join Magento Community Engineering Slack and ask your questions in #github channel.

[sirugh]

This isn't an answer to the problem, but I want to point out that in v3 there seems to be a way to override the default fetch policy when initializing your client: https://www.apollographql.com/docs/react/api/core/ApolloClient/#example-defaultoptions-object

[jimbo]

As I understand it Apollo Client v3 changes how some of this will work. It would be nice if documentation contained a table...

*snip*

I'd guess there are only a few patterns actually needed, and this documentation would save developers learning what/why Apollo does before they spread bad patterns around the site.

This is a very good suggestion. You're right, fetch-policy and query states (and thus conditional renders) are very interrelated, and more so in Apollo 3. Having a resource to consult would be useful internally as well as externally. We'll bring it up with the rest of the team.

[awilcoxa]

Created PWA-869

[jcalcaben]

Clearing my assignment to give the community an opportunity to pick up this issue if they are interested