[yodon]

The issue is not that there is a simple feature that's inadequately documented. It's that I have no high level understanding of what all the pieces are and how they fit together. Tell me exactly what I'm getting from Apollo that I don't get from fetch. Tell me what caching does, when, how, and how to invalidate it. Tell me about links and middleware. This is a very complex batteries included technology. I don't even feel like I understand where the batteries go, much less what they are doing for me, I'm just copying and pasting code that others have used into my projects and hoping I have about the right amount of stuff included.

Your customer didn't write all the Apollo code. The docs feel like they are written with the assumption that we understand the architecture and goals as well as you do and we just want to do some simple task with it to get started. I fear however that this is fundamentally not a docs problem. It feels like a problem where the Apollo devs didn't start by asking "how can I build something that will be easy for 3rd party devs to use and understand", they started with "oooh that would be cool". Urql feels like it started with a very simple and clear conceptual foundation that provides a clear roadmap for how and where more complex features get attached.

If you can reduce Apollo down to a clear and simple framework in the docs that actually covers everything that it does, then you're golden. I suspect however that the underlying architectural simplicity that would be required for you to do this doesn't actually exist. If it does, you face a docs problem, if it doesn't, then docs are just a bandaid.

[true_religion]

You can’t invalidate the cache in Apollo. You have to clear all items, or update a specific part to a new value.

It’s not a simple key value cache, but a graph of values, which makes invalidation more complex but still in my opinion that is a huge oversight.

Hopefully an Apollo dev can give us some insight here: why is the cache a requirement? Why is it threaded into every bit of code? I’ve seen so many bugs from the cache, and I know there is a technical reason it has to be part of the core codebase, but I have forgotten why.

[peggyrayzis]

The normalized cache is the one of the main value props of Apollo Client. It optimizes reads, automatically updates queries without a refetch for some mutations, supports optimistic updates, and can also return partial data for large queries. If you don't need a cache, then you can use fetch, graphql-request, or even Apollo Link to fire off a simple GraphQL request. You also don't have to use our cache implementation (apollo-cache-inmemory) with Apollo Client. There are other implementations that make different tradeoffs.

For what it's worth, we are rearchitecting parts of the cache to support invalidation and garbage collection for Apollo Client 3.0. The only reason why we don't have it yet is because it's a tough problem to solve - one mutation could invalidate an infinite amount of queries. We're committed to solving this soon though because we know the community really wants it.

[peggyrayzis]

Thanks for the thoughtful response, this is all helpful feedback that I will share with the team.

It's been on my backlog for a while to rewrite the Apollo Client intro section to give developers the high level overview you're looking for. Now that Apollo Federation is out, I have some time on my calendar to do exactly that. :) Would you be open to reviewing the new section once it's done? If you're interested, send me an email at peggy [at] apollographql.com.

If it's still confusing after that, then we can chalk it up to a problem with the library. I suspect that it's a docs problem since the intro hasn't been overhauled since I joined the company almost 2 years ago.