Apollo-client: HoC methods removed from docs

[ghost]

Intended outcome:
Docs should have component and HoC example toggle.

Actual outcome:
Many doc pages have completely removed the HoC method in favor of the component method. There is absolutely no reason to remove supported method examples with the new method. There is a time and place for both functionality.

How to reproduce the issue:
Visit any recent updated documentation such as https://www.apollographql.com/docs/react/essentials/queries.html

Version

• Latest docs

[ooade]

It's not gone. It's still here https://www.apollographql.com/docs/react/api/react-apollo.html

[ghost]

@ooade
Some pages still have HoC. However, a lot of pages are completely in component now.

[hwillson]

The removal of a lot of the docs HOC examples was intentional. We love the extra simplicity the component + render props approach brings to the table. While the graphql approach still works (and is well documented in the React Apollo section of the docs), we're intentionally demonstrating the Apollo Components approach first and foremost. Thanks!

[ewyler]

Can you elaborate on the "extra simplicity" point? I'm failing to see the simplicity of Query/Mutation component approach vs. the HOC approach - a component which depends on several queries, or a query and a mutation or two, ends up with deep nesting of Query/Mutation components whereas the HOC approach has a simple compose call and then a single component that takes several properties corresponding to the query/mutation data. I haven't found a use case where Query/Mutation leads to a simpler structure, "simpler" defined as requiring less code and less nesting

[KarandikarMihir]

@ewyler I agree. Not really a fan of nesting multiple queries and mutations. I'm finding it super awkward to use the render props pattern.

[vladshcherbin]

While the Query render props approach looks somehow okay, Mutation one looks just ugly. The abuse of this pattern is so bad compared to clean hoc one. I'm not even talking about multiple queries, mutations - the code looks like a mess. I wonder if hoc versions will be removed in future versions.

[hwillson]

I wonder if hoc versions will be removed in future versions.

@vladshcherbin No, we're not planning on removing the graphql HOC. Actually, behind the scenes graphql re-uses the render prop code, so maintaining both approaches adds very little extra work. Please feel free to use whichever approach you prefer.

[vladshcherbin]

@hwillson that's what I hope. I'm using HOCs everywhere because of the simplicity and convenience they give and it will be a real pain to refactor them. However, in the docs it's a hidden gem for newcomers.

[chronick]

+1 for HOC docs - I vastly prefer using them over components and wish the docs would include both approaches. Using one over the other seems like a personal preference, so why is the HOC use being discouraged so heavily? If there are no plans to remove the pattern, then they should be documented.

[cquillen2003]

Coming from Redux, using the HOC is so much cleaner than using the Query and Mutation components. Submitting API/database queries belongs in a JavaScript function not a UI component IMO.

[kevinthecity]

Also ehcoing similar feedback from others - I like both patterns for different things, but definitely prefer the HoC for more complex use cases. I find the Mutation component to be fairly clunky compared to an HoC implementation. Especially in TypeScript.

[barbalex]

Seems like react hooks could make the compose + hoc approach even better. Is anyone working on building a withData hook?

[vladshcherbin]

@barbalex I'd suggest you to open a new issue with such feature request if there isn't any similar one already 😉

[barbalex]

@vladshcherbin there is an issue for it: https://github.com/apollographql/react-apollo/issues/2539
And even a separate implementation: https://github.com/trojanowski/react-apollo-hooks

[b33son]

HOC is much cleaner. The render props method leads to nasty spaghetti code. I'm surprised you guys aren't pushing HOC more.

[jfrej]

The docs definitely need some clarification.
Currently the "Setup and Options" section says:

The graphql() container is the recommended approach for using Apollo with React and it is a React Higher Order Component. (...)
Over the course of the rest of the docs, you will see the graphql function used almost everywhere as the best way to use Apollo and React together.

(emphasis mine)
https://www.apollographql.com/docs/react/basics/setup#in-your-ui

So the above suggests the HOC as the preferred (and the best?) approach, but the rest of the docs use Apollo Components instead. Super confusing.

[jay-manday]

I agree, this has been a frustrating pain point on my end as well. We've had some awesome successes here @numina with apollo and very excited about the tooling but the lack of clarity around this in the docs are definitely confusing.

I've tried several different approaches as well as nesting query components with react-composer to chain more complex operations across our applications, but haven't found a clean solution yet for working with the mutation components that are dependent on fields from remote services.

For my part I find the compose(...) method much more elegant and intuitive, especially for use with client side mutations that are dependent from data via remote services.

[vibecode]

I’m new to Apollo and after a couple weeks of using it felt fully the pain of dealing with the awkward mess which render props approach in this case drives to. Then I stumbled to some old examples and admired how simple and clean it was before. You definitely shouldn’t deprived new users from all the possibilities and force them to use the declarative approach, both approaches should be documented explicitly.

[zlwu]

The official doc is lacking HOC part compared with the render props part. It will mislead the new comers to over-mix data layer and the presentation/component layer in their code by using render props everywhere. In some cases the HOC is more neat to decouple data and view (also I agree that in some cases render props are more reasonable).
Anyway, the coming react hooks will be another great choice. And I suggest to treat these different idioms equally in the docs together with the pros/cons to help making choice.

[ayushkamadji]

I'm looking into using Apollo Client for my next project and I was feeling uneasy reading the essentials doc seeing the components approach presented. Maybe it's because I was using react-redux connect previously. In any case I was imagining a nasty nesting of Query and Mutation components.

So I went and literally googled "why apollo client feels weird" and got this github issue as the first match. I'm surprised to find out there is a HOC approach quite similar to react-redux connect() which I would much prefer.

Even if the Apollo team believes the component approach is the right way forward. Would it not make sense to keep introducing apollo client from a HoC approach since I'm guessing most of new users will be coming from a similar approach from react-redux? Or is Apollo trying to be extra opionated about HoC vs. render props? What am I missing?

[aacotroneo]

I came back to Apollo after a few months and not finding the HOCs was weird. At first I thought that the Query, Mutation components were just there because they were easier to explain to new users, but I'm surprised it's the suggested way to write the code.

I used to use the HOC to process/transform props, encapsulate some logic. Have dumber components. Is that not a good thing anymore? Why mix core javascript logic with jsx? I feel I don't understand the paradigm at all.

[kleber-gueriero]

To try to add a perspective of who's starting with apollo-client, I can say that I started using it at the beginning of 2018, only some time later I got to know about the HOC approach when looking at the "recompose patterns" link and until now I wasn't much secure about the way to go, since the whole docs doesn't present much about it.

Now, I'm starting to use the HOC approach, which already looked to me to be cleaner when I first read about it, but just now, facing some of problems of the component approach, I'm going to start using it.

IMHO, I don't see this idea of "hiding" this part of docs on purpose a good idea, since there is a place where it's cleaner and maybe a better approach. Furthermore, it seems to be good to give users of library the option to choose the approach that best suits for them.

[vladshcherbin]

It's just a hype train, render props was a hype with hoc blame - the docs were quickly changed to using render props, now hooks hype is coming - pretty sure docs will have them asap.

I know some people, how didn't know about hoc's in apollo and had to suffer using render props before I told them that hoc's were inside all the time and working with them is much easier.

This situation is sad but the hype train in react is really strong.

[coopersamuel]

Are there any thoughts from the Apollo devs on _why_ the render props API was implemented? Or an even better question: is there a compelling reason (beyond personal preference) to use the render props API over the HOC implementation? I too have found the render props API to be clunky and for some reason I can't find anyone talking about this except for on this thread.

[jkoontz2010]

Just a heads up for anyone searching for HOC documentation like me, hwillson is right. It's covered very nicely in the docs, especially for API docs: https://www.apollographql.com/docs/react/api/react-apollo

[AndrewMorsillo]

As someone new to Apollo (through AWS Amplify) this also caused me a lot of confusion. The amplify docs use the hoc but I also saw the render props pattern so I wasn't sure which to use. To me the render props pattern isn't ideal. It mixes your data loading code into your presentation code which I can't see any benefit to doing and IIRC has long been considered a react anti-pattern (you should pass props into dumb components instead). It is messy syntax wise, makes components tightly coupled to their data loading, and overall less react-functional-programming-ish.

@hwillson can you share some reasoning about why the render props method is now preferred? I may be missing something but as I outlined above it seems to have a number of significant downsides.

[aacotroneo]

as vladshcherbin said it was the train at that moment. Now it's hooks, which Apollo will surely support (there's already a popular library for it).
Comfortably, migrating from render-props to hooks would be harder (jsx nesting mixed with mapping logic) than adapting a HOC structure in which jsx and logic is not mixed up 😁

[Aid19801]

May 2019 and a quick look for the HOC documentation affords me a welcoming:

[jfrej]

@Aid19801 What link are you trying to access?

You can create HOCs using the grapqhl() function, which is documented here: https://www.apollographql.com/docs/react/api/react-apollo#graphql

[Aid19801]

Thanks @jfrej sorry i was trying to access one of the ones shared above but you're right, the docs are accessible via googling. Also i found a blog that covered HOCing apollo which helped. x

[nandorojo]

Coming from Redux, using the HOC is so much cleaner than using the Query and Mutation components.

Couldn't agree more. It would be great if all of the docs had examples for the HOC. This did help, though: https://www.apollographql.com/docs/react/api/react-apollo

[hwillson]

The HOC API docs are still available, in the @apollo/react-hoc section. That being said, we'd love to get more HOC examples into the docs, in the code toggle boxes.

If anyone is interested in contributing HOC examples that line up with the hooks and render prop examples, we'll get them merged. Thanks!