[yodon]

Excited to see some competition for Apollo. Apollo may do lots of things but exactly what and why and how remains a mystery to me. Apollo just feels needlessly large, opaque, and inadequately documented to me. Reading about urql, the combination of minimalist architecture with first class support for React hooks sounds like just what I'd been hoping would emerge.

[peggyrayzis]

Hi from Apollo! We appreciate your honest feedback. Part of my team (Developer Experience) is responsible for our documentation. What features are inadequately documented? We'd like to fix that for you if we can.

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

[wongarsu]

https://www.apollographql.com/docs/react/api/apollo-client/ is pretty terrible all around.

As a trivial example look at the documentation of client.query(), the most fundamental function. It lists the options for `errorPolicy` and `fetchPolicy` but doesn't explain them. The links lead nowhere (that's true for at least half the links on that page). You have to remember where to find that the Apollo React documentation instead. `fetchResults` is described like something that sounds like a boolean, but for some reason it has the type any. `metadata` is described so vaguely that I have no clue what it does. `query` is unhelpfully described as being of type `DocumentNode`. I'm left to guess that a gql string propably results in a DocumentNode, but I'm not sure everyone makes that deduction. `variables` is pretty much the only decently described parameter.

And that's for the simplest function. Just below that the `subscribe` function has a fetchPolicy parameter without giving any idea how fetchPolicies interact with subscriptions (how does a "cache-only" subscriptions work???). And I really hope I never want to directly use an ObservableQuery class, 7 of 11 members don't even have a description.

The documentation for the react stuff is mostly fine, but once you have to go beyond that you are on your own and end up reading source code to figure anything out.

[Trufa]

I am enjoying using apollo, it's hard to explain but at the beginning the language of the docs seems foreign (think apollo link) and the site feels huge, it's not a particular problem just more a matter of the feeling /impression it gives. Uninviting and intimidating is the words that come up.

Vue's documentation is a good example of the opposite, it feels friendly an accesible, it has a nice flow to it. Apollo has the opposite feeling even though everything seems to be documented and everything is explained.

Probable more an organization and presentation issue than a content issue.

Just my 2c.

[underbluewaters]

I've often found the react-apollo docs in particular confusing. They often rely on opaque type definitions to describe argument formats. For example, it took me a long time to understand what to pass to the `refetchQueries` argument of a Mutation component. A set of examples for common scenarios would be helpful.

[gorgonian]

I agree with other commenters that Apollo is too big and too opaque to easily understand. The docs don’t have enough examples and are out of date in some places (see link-state). I’ve had a lot of confusion while trying to implement Apollo in my current react project.

I’ve also seen some erratic behavior from Apollo. While testing I found that Apollo deduplicates queries too aggressively. I made some mutations with slightly different inputs (think naming a new item “a” and another one “b”) and several of them would not get sent. In my example it would have resulted in two new items on the server but instead only one was created, because the second mutation wasn’t sent.

I also found that using the `called` flag in a mutation function child was basically useless because sometimes it would be false even if the mutation went through. I switched to using the onCompleted prop in the component and that’s worked.

Another thing I ran in to is that Apollo sometimes can’t update the store because I sent a query without an ID field. It throws an error. If an ID is required for all queries the docs should say so.

Also I don’t think the docs say that you should return any fields you update in a mutation, to make sure the store is current. I think I found that out on stack overflow.

[Capaj]

> If an ID is required for all queries the docs should say so.

they absolutely should. It's not really needed every time, but when you have a queries with IDs and without-that's when the cache blows up. They even a have a snapshot test for this unfortunate behavior: https://github.com/apollographql/apollo-client/blob/master/p...

[true_religion]

Deduplication shouldn’t work on mutations at all! There has got to be something else wrong. If I were to guess, it’s probably an issue with the Apollo React interface.

Also IDs aren’t required for cache updates, only the typename.

[Capaj]

> Also IDs aren’t required for cache updates, only the typename.

this is very inacurate. The problem happens when an items is cached with an ID and then another GraphQL request tries to cache it without and ID or vice versa. This is where the apollo-cache-inmemory blows up with an error like this: https://api.media.atlassian.com/file/f82c0ee8-2412-4f1b-8027...

There's even a test for this unfortunate behavior: https://github.com/apollographql/apollo-client/blob/master/p...

[oaxacaoaxaca]

- The `Query.variables` prop. The docs don't explain very well when exactly the network call will be reinvoked, especially if the graphql query has variables with default values (there's an open issue about this with little activity: https://github.com/apollographql/react-apollo/issues/2715).

- The `Query.skip` prop. I'd like to know all of the expected behavior for when this prop is used. For example, I've noticed that when skip is true then the render prop function's `data` object is always undefined, even though the data is there! Also when skip is true and you manually trigger a refetch elsewhere (for example when running a mutation with `refetchQueries` specified), the `onCompleted` prop doesn't get called, even though the query was in fact refetched and completed.

Those are just recent things I've noticed. Also for the record I don't mean to sound like I'm throwing shade. I appreciate all open source work and the Apollo projects are massive open source contributions, so thank you :)

[peggyrayzis]

Really appreciate your feedback. Let me pass it along to the team. I agree that we could do a better job of documenting when queries are reinvoked depending on what options and variables are set.

For skip, the behavior with refetchQueries sounds intentional since the refetching happens within the Mutation component. I don't think we pass information about whether the skip prop is set on the Query component to the refetchQueries array (https://github.com/apollographql/react-apollo/blob/master/sr...).

[svachalek]

I've also recently started using Apollo client. The basic usage was pretty straightforward (although either I don't understand something about the loading flag or it just doesn't work very well). But in dealing with the loading flag issue I ended up writing middleware and there's a whole lot of types involved, links and middleware and afterware that seem needlessly complicated (why is middleware and afterware different, why does it seem like it's reinventing either Rx or Promises instead of just using one), compared to Redux middleware which is trivial to understand, write, and use and does basically the same thing as far as I can tell.

Possibly this is just a doc issue but it seems like the API could benefit from some streamlining.

[lewisl9029]

Hi, I'd love to see an example for links that showcases how links could interact with React state/props.

For instance, in the 401 logout example (https://www.apollographql.com/docs/react/advanced/network-la...), it imports a logout function from a separate module to call on 401, but I'd like to ideally have 401s trigger a change in some React state instead (possibly by passing through a state changing function as a prop to Apollo's Provider component?), and it's not entirely obvious to me from the docs how one would accomplish that.

[true_religion]

At work, we are a fairly established company with an existing codebase. We don’t use Apollo React, simply the client and Apollo explorerer. I would like better documentation for the vanilla client.

Personally, I have no trouble with it’s usage since I have been dealing with it for 2 years, and I keep up with the GitHub changesets but new devs have a harder time on boarding since all the links on the site seem to lead to a framework specific documentation.