[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:

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