Prominently advertise differences from main competition

[lorensr]

Further help would be including in docs at launch a list of the other major libs and what the differences are.

Great idea! As a good side-effect, this will force us to really understand those other libraries.
apollographql/apollo-client#7 (comment)

When I tried to get my React friend to use Apollo for data, they were like, "Why not use Relay?". It will often be the first thing React devs think when they see Apollo. So I think it would be good to say why here http://docs.apollostack.com/ and maybe here http://apollostack.com/. While the design doc https://github.com/apollostack/apollo-client/blob/master/design.md mentions Relay, I think it would be nicer to have something shorter that you can put up front, like "Simpler to use than Relay, plus reactive, etc" or something.

Similarly, you could say why server better than GraphQL-JS / express-graphql here: http://docs.apollostack.com/apollo-server/index.html

Related: apollographql/apollo-server#2

[stubailo]

Definitely a good idea. I agree that Relay will be at the front of everyone's mind. Question: Should we talk about the current feature set or the goals? Because right now Relay has a lot of advantages regarding pagination, optimistic UI, fragments, etc, but we are working on all of those; should we wait to post the comparison or just tell people what the future holds?

[stubailo]

Another question - if Relay is already working for people, why should we even encourage them to switch? Eventually we will have some paid services, but we can just as well integrate them into Relay. Although I guess it's more about giving people the tools to understand which option is better for them, rather than pushing people in a certain direction.

[lorensr]

Could post now what the current and future comparison is. "Apollo vs. Relay: Apollo is simpler than Relay. It works well and is being used in production. We have big plans for the next few months. When Apollo reaches v1, it will be better than Relay because..."

[AlecAivazis]

One thing that I think apollo does a lot better than relay (to the best of my knowledge) is incorporating local data. It's really clear to me how I would add additional things to my apollo store (just add another reducer) but the answer is a lot less clear to me in relay.

[helfer]

I like where this is going, but I'd like to make one small course adjustment (definitely agree with @stubailo there):

Rather than saying "Apollo is (or will be) better than Relay, because ...", we should have a table comparing the two and maybe a short paragraph saying: "You should choose Apollo over Relay if ...".

We definitely have a lot of strengths, but there might still be cases where people would be better off using Relay, and we should be 100% open about that. If we want to hint at what Apollo is going to be, we can always add a small asterisk in the box and put a note at the bottom: planned for v1.

[dallonf]

Here's some questions I would ask (because I'm actually curious about the answers!), as somebody who's been watching both Relay and Apollo at a distance, but mainly familiar with Relay:

• Does Apollo require you to structure your GraphQL API in a certain way, like Relay does?
  • If not, can it still maintain a normalized cache in what data is not duplicated and does not become stale?
• Does Apollo work well with some of React's more advanced applications, like React Native or server-side rendering? (The answer is yes and no respectively for Relay, iirc)
• Do I need a Babel plugin to start using Apollo?
  • If not, are my GraphQL queries easily minifiable? (I worry about lots of needless whitespace when using template strings)
• Does Apollo have a similarly byzantine process of handling mutations?
  • If not, can it handle optimistic updates well?
• Does Apollo support server-sent updates in any form? (examples: reactive queries, server-sent events, websockets)
  • If yes to reactive queries, is there also a way to reactively inject data into the cache if I've gotten it from somewhere else? (ex: I get a server-sent event from a non-GraphQL source, but I know how to map it to my GraphQL cache, so I want all the UI that's referencing that data to immediately update)

Now, I don't expect these questions to be answered here... I can easily go look these up myself! But I think these would also be many of the questions of somebody familiar with Relay and only passively interested in Apollo, and would be good to answer prominently on the site.

[lorensr]

Yeah, makes sense!

On Mon, May 2, 2016 at 7:18 PM, Jonas Helfer [email protected]
wrote:

I like where this is going, but I'd like to make one small course
adjustment (definitely agree with @stubailo https://github.com/stubailo
there):

Rather than saying "Apollo is (or will be) better than Relay, because
...", we should have a table comparing the two and maybe a short paragraph
saying: "You should choose Apollo over Relay if ...".

We definitely have a lot of strengths, but there might still be cases
where people would be better off using Relay, and we should be 100% open
about that. If we want to hint at what Apollo is going to be, we can always
add a small asterisk in the box and put a note at the bottom: planned for
v1.

—
You are receiving this because you authored the thread.
Reply to this email directly or view it on GitHub
#34 (comment)

[stubailo]

Wow, that's an AWESOME list of questions! In fact a lot of them target directly the differences between Apollo and Relay. So is a good format for this page something like an FAQ in the docs, where people can add PRs with questions and updates?

[stubailo]

I know you said we don't have to answer here, but I'm going to do it anyway:

Does Apollo require you to structure your GraphQL API in a certain way, like Relay does?

No.

If not, can it still maintain a normalized cache in what data is not duplicated and does not become stale?

It can optionally interpret IDs in a pluggable way (haven't added that to the public API yet, but it's well tested already!) so you can customize normalization as much as you want. For example, you could normalize based on id + typename if you wanted to, which is not possible in Relay.

React Native

In theory yet, although some people have run into various bugs: https://github.com/apollostack/apollo-client/issues?q=is%3Aissue+is%3Aopen+label%3Areact-native

@martijnwalraven is actively working on making Apollo+React Native a great combination.

server-side rendering

Definitely yes - since we use Redux under the hood, store hydration is easy as well. @jbaxleyiii has a few examples of this, which we need to add to the docs.

Do I need a Babel plugin to start using Apollo?

No.

If not, are my GraphQL queries easily minifiable?

I suspect that gzipping your JavaScript code (which everyone already does) eliminates any concerns about minification of strings, but we are working on making an optional babel plugin to eliminate the need to compile queries at runtime.

Does Apollo have a similarly byzantine process of handling mutations?

No.

If not, can it handle optimistic updates well?

We haven't investigated this yet; the hope is that we will be able to take advantage of Redux-Optimist or similar to do it in a way that will be familiar to Redux developers, and without making mutation syntax more complex.

Does Apollo support server-sent updates in any form?

Not yet, although this will eventually be a priority. Right now the best thing to do would be to have an event bus that then calls refetch on the appropriate queries. But having it be a first-class feature shouldn't be too hard and is definitely something we want.

If yes to reactive queries, is there also a way to reactively inject data into the cache if I've gotten it from somewhere else?

This should be trivial via Redux - you just write a reducer that operates on the apollo store using modules you can already import from apollo-client, and that will propagate the changes properly.

More questions, please!

This is super helpful, and knowing what people are going to ask about is critical to presenting the library well.

[lorensr]

So is a good format for this page something like an FAQ in the docs, where people can add PRs with questions and updates?

I find that FAQs are less organized than documentation, which is grouped in sections and has concise non-quesion-formatted headers. Could format it as docs, and to encourage questions, could say at top of page "Got a question? Let us know (linked to new issue)".

I like the idea of having a short summary on front page and linking to the longer Apollo vs Relay doc. If helfer's table comparison is short enough, it could be the summary, or the table could be at the top of the doc.

[ksmth]

Ok, so I'm looking into replacing Relay with something else, possibly apollo-client. It'd be really helpful to have an overview of Apollo's features in contrast to Relay, implemented and planned.

It took me quite a while to figure out that a few key pieces are missing for a Relay replacement as of right now, i.e. query aggregation and optimistic mutations. It'd be helpful to know that :)

[stubailo]

That's a great point - it would be good for people to know what they might be missing from other options, and also what they gain. I think the main missing things end-user wise are:

1. Query composition Query composition apollo-client#148
2. Optimistic mutations
3. Fancy pagination handling

We have an advantage in certain areas though, like incremental adoption, easy polling of queries, and no restrictions on server schema.

[leebenson]

If not, are my GraphQL queries easily minifiable?

I suspect that gzipping your JavaScript code (which everyone already does) eliminates any concerns about minification of strings, but we are working on making an optional babel plugin to eliminate the need to compile queries at runtime.

What about queries that are sent to a server from the browser?

[GreenAsJade]

How's this coming along? I'd love to see this table, couldn't find it yet.

One question is "who's behind these, how well supported are they?"

[vonwao]

So it looks like optimistic UI has been implemented:
apollographql/apollo-client#336

And query composition too:
apollographql/apollo-client#148

A little hard to find docs about it, but actually there is this:
https://medium.com/apollo-stack/mutations-and-optimistic-ui-in-apollo-client-517eacee8fb0#.cy4l4g1fy