Urql: a GraphQL client library

From recent bundle audits of e-commerce sites built with React, less than 20% of the code was actual custom site code and the remaining 80% was from dependencies.

If the bundle size is 550kb min/gzipped, that's 110kb of app code, and 440kb of dependencies. Some of the largest dependencies in a recent audit were: moment (60kb), swiper (32kb), lodash (24kb), react-select (26kb), raven.js (12kb), polyfills (25kb), mobile-detect (15kb), and then a bunch of smaller dependencies that made up the remaining 300kb.

Using this performance budget calculator you can quickly see how each 25kb of JS adds ~.3s to your TTI on a mobile phone:

https://perf-budget-calculator.firebaseapp.com/

If developers shop around for smaller alternatives of each dependency, then they can cut their load times pretty drastically.

It does incrementally make a difference. You want all your libraries to stay under a certain budget if you don't want to hit your users with a 500 KB bundle size.

It is not only about how long it takes to download, it is also about parsing that amount of code in low end phones.

When talking about a few kilobytes, it’s less the download time than the parse time that’s the main performance concern.

It is pretty cool indeed, you can watch his presentation of the project here https://www.youtube.com/watch?v=Sq2M00vghqY (disclosure, I organize this conf).

Yes, we're already working on SSR support! https://github.com/FormidableLabs/urql/issues/218

Since we didn't want to go down the same road as some other libraries that use renderToStaticMarkup and a promise-queue, we've already built a supporting package so that we can implement SSR-support using suspense. (At least the unstable API of suspense; which is as simple for us as adding throwing promises to our components and hooks) https://github.com/FormidableLabs/react-ssr-prepass

It tips it all on it's head. It's generally a POST request and so doesn't cache at alls (you can configure it with a long GET request). All caching is done client side but at object level, including not requesting fields that you might have already requested previously on other calls.

It's fantastic at scale for web applications (far better than the REST apis it has replaced since over-fetching isn't a concern). I don't work on content sites or anything where edge caching applies though, so YMMV. (All our static content is served via CDN but API content is not generally cachable).

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.

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.

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.

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.

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.

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

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.

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.

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.

A more consistent documentation experience. A lot of code examples import various modules, but those modules have no documentation. For example: Docs > Client > Apollo Link mentions `graphql-tools` and schema stitching, with a link to read more. Clicking that link takes you to a page that says it's deprecated, and then links to a blog post about why.

Another example: Is `apollo-link-state` deprecated? The docs for `apollo-link-state` don't mention that, but the Local state management page in Apollo Client sure says it is.

Oh cool, they have a package for urql: https://graphql-code-generator.com/docs/plugins/typescript-u...

I might try it out once it supports the new hooks.