I really like the simplicity of the core library and this approach of starting from a simple core and building on top of it with the same primitive for extensibility as the one you offer to users.
Apollo has also been moving in this direction with composable links, but in a zig-zaggy way since it's still got some baggage from its days as a monolithic library, and recent decisions to move local state management into core seems to be backtracking from that effort somewhat, so it's great to see some competition in this area that really approaches extensibility as a first class citizen rather than an afterthought.
With that said, I'd love to see an officially supported normalizing cache implementation as well, in addition to the simple document cache Urql currently provides as a default:
Apollo and Relay's normalizing cache helps ensure a single source of truth for every piece of server data, which is incredibly valuable for non-trivial apps that have the same pieces of data fetched in multiple places that would otherwise have to be manually kept in sync, which anyone who has ever tried to do so can tell you is generally extremely tedious, error prone, and likely a frequent contributor to user-facing bugs. That to me is by far the most compelling value prop of GraphQL clients like Apollo and Relay. It'd be great if I didn't have to choose between automatic normalization and a more flexible extensibility model (fwiw, I'd choose the former).
Cheers! I'm happy to say that a normalising cache is indeed in progress and we're planning to finish it soon https://github.com/kitten/urql exchange-graphcache
We've got the cache itself done but are just figuring out the API for its customisability in terms of cache resolvers and such
Have been playing around with urql on a project for a couple of months now, mainly due to the small bundle size. Urql is 7.5kB min+gzip, where Apollo and Relay add ~30kB min+gzip!
Great to see Formidable investing further in it, I am very excited to see first class extensibility.
> Urql is 7.5kB min+gzip, where Apollo and Relay add ~30kB min+gzip!
How is that 22.5kB making any difference? Unless you are working on a project that will be used on very slow connections I see no point in choosing a library basing on such small difference in size. And if you really are targeting those slow connections then maybe going SPA is not the best choice?
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:
Fixating on package size alone is missing the forest for the trees. A good library can massively reduce your application size and pay for itself many times over.
For example, Relay removes the need for a lot of Flux and network request boilerplate. Going beyond that, it can collapse serial network fetches down into one request, massively speeding up page loads.
(This doesn't apply to moment, that library is just designed in a brain dead way).
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.
> if you don't want to hit your users with a 500 KB bundle size.
Still I do think if you are building a web application (and not a static site or a blog) it is expected it can take a second or two to load it for the first time. 500 KB bundle is nothing wrong in that case.
The initial question of why did you make something iteratively better (in terms of size). It's only 20KB. Can be used to stop progress in any field by replacing the keywords.
I would hate to use something built by people with the attitude that compromising on performance when you don't need to is OK because it falls in line with current expected ranges.
It might be expected, but I have to admit, there is a certain joy to using a website that loads instantaneously (like Hacker News). Whether or not that joy translates into additional revenue to justify the costs is another question entirely...
There is also the new GraphQL integration into mobx-state-tree that was just announced last week by the author of mobx, you can check it here https://github.com/mobxjs/mst-gql
> this project closes the gap between GraphQL and mobx-state-tree as state management solutions. GraphQL is very transport oriented, while MST is great for client side state management. GraphQL clients like apollo do support some form of client-side state, but that is still quite cumbersome compared to the full model driven power unlocked by MST, where local actions, reactive views, and MobX optimized rendering model be used.
MST and GraphQL together does sound like a pretty serious win
GraphQL is amazing. Building an API and then playing around with it in GraphiQl is really a exciting experience.
I've played with Relay (relay-modern looks great, but when I needed to pick a graphql client it hadn't been released yet). Apollo is frustrating: it's big and complicated and obsessed with stuff that I don't want (link-state and a bunch of product up-sells).
I'm glad urql is getting some more attention and I'll definitely give it a spin.
I was just looking for a smaller/simpler graphQL client. But I cannot try this yet as I need SSR (I'd need to remove SSR from my app in order to implement this library)
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).
urql's great, and the maintainers are super helpful and friendly. I've been using it on a project for a couple months now. Very straightforward and plays well with TypeScript. My one criticism is that it doesn't quite do enough in some cases, but I haven't spent the time to learn much about exchanges. As the ecosystem grows, I see this problem going away.
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.
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.
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.
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.
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.
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.
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.
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.
> 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...
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.
> 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...
- 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 :)
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...).
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.
I _really like_ the implementation with hooks. I experimented with a similar pattern on top of Apollo on a side project. Going to play with urql today! Thank you!
Hi from Apollo! My team (Developer Experience) is responsible for making sure you can find what you need in the docs. What improvements would you like to see?
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.
Similar to the deprecation issue, a number of Links still say "under active development" or similar pre-release "warnings" in their GitHub READMEs but that isn't reflected in the documentation site, making it tough to figure out what is considered stable and what isn't without jumping back and forth between GitHub and the documentation site, and there's still questions of whether or not perhaps the README warnings are stale. It would also maybe be great to have something of a roadmap of when those links might be considered "production ready" especially if the documentation site is already recommending them as project solutions.
The example to mind is last time I was trying to do something (a few months back) `apollo-link-rest` was highly recommended in the documentation as a potential solution, but yet visiting the GitHub for it seemed to be saying the exact opposite that it wasn't ready yet and was filled with massive API shifts and bugs/issues to iron out before "production ready".
Excited to try this out! Also glad to see Apollo getting some more competition. I made a side project last year with the Apollo ecosystem, it confused the hell out of me.
really interesting, but i took a look at the docs, and they 100% look like urql is only compatible with react. Can I use urql with Vue.js, or would I just be inviting misery upon myself if i tried?
That's just moronic, I would even go as far that GraphQL is something only backend dev could love, the only benefits frontend dev gain using GraphQL is not having to wait on backend dev to change some random endpoint response. From a backend dev perspective GraphQL completely removes that chunk of work, solves the issue of over-fetching/under-fetching, and more importantly allows you to map your REST APIs into a single interface (and break your monolith into microservices transparently).
If you're API is a todo list CRUD, then yes, you prob don't need GraphQL.
If you're a backend dev that makes APIs, you probably won't like GraphQL (I am not one of those, BTW). If you have a big project with a team split into API devs and app devs, and you have to wait, then that is poor planing. Plus, just wait, jeez. Don't blame the separation of the work into roles for your problems, it is usually good, and often necessary. Then again, if you're full-stack developer, you can just go fix the endpoint yourself.
I know the argument about over-fetching with an API is that you have to make one call, than loop through and make secondary calls, but you can mitigate that, it is rare, and is actually fine. Ad-hoc data modeling encourages over-fetching in it's own way. You always make in-situ calls for exactly the model shape you need right there. "That model is not quite the shape I want, I will do another query." Plus, with pre-defined data models you can save them, in like a state object, they are more reusable. You can even use them in a totally different program.
Apollo has also been moving in this direction with composable links, but in a zig-zaggy way since it's still got some baggage from its days as a monolithic library, and recent decisions to move local state management into core seems to be backtracking from that effort somewhat, so it's great to see some competition in this area that really approaches extensibility as a first class citizen rather than an afterthought.
With that said, I'd love to see an officially supported normalizing cache implementation as well, in addition to the simple document cache Urql currently provides as a default:
https://formidable.com/open-source/urql/docs/basics/#code-cl...
Apollo and Relay's normalizing cache helps ensure a single source of truth for every piece of server data, which is incredibly valuable for non-trivial apps that have the same pieces of data fetched in multiple places that would otherwise have to be manually kept in sync, which anyone who has ever tried to do so can tell you is generally extremely tedious, error prone, and likely a frequent contributor to user-facing bugs. That to me is by far the most compelling value prop of GraphQL clients like Apollo and Relay. It'd be great if I didn't have to choose between automatic normalization and a more flexible extensibility model (fwiw, I'd choose the former).