React-apollo: Add back query, mutation, and subscription HOCs and provide first class documentation support

[haleykoike]

This issue is intended to start a discussion on the way forward for react-apollo now that the new Query, Mutation, and Subscription components are out with 2.1.

Prior to 2.1, the graphql HOC was the only way to pass data from apollo into your React components. Now, with 2.1, it's great that there is now a component based approach for passing the data to your components.

However with it, I see that briefly there were query, mutation, and subscription HOCs that were exported as well but then quickly removed from export.
https://github.com/apollographql/react-apollo/pull/1815

The purpose of this issue is not to get into a discussion of which is better HOC vs render prop pattern. People feel strongly on both sides, but it's fair to say that at bare minimum they are a stylistic choice and both have relevant use cases. As such, it's best for react-apollo to support both and provide documentation for both.

Coming from building a large production React app with Relay Classic and working with Relay Modern, the most refreshing thing I've found about Apollo is how much less opinionated it is. One of the traits Apollo states in the documentation intro is being "Small and flexible". Flexibility is the key.

While the graphql HOC is still available, removing it from the documentation save for the API section, and removing query, mutation, and subscription HOCs feels like a drift towards react-apollo becoming opinionated in a bad way.

react-apollo should simply provide the framework for fetching / mutating graphql server data into your react application. It should not be opinionated in how you construct your components to receive that data by requiring the render prop pattern over the HOC pattern.

Adding back the query, mutation, and subscription HOCs along with documentation for them ensures that react-apollo remains flexible for both use cases.

/label discussion
/label docs

[doomsower]

I'm worried by this change too. I'd like to use both new components for simple queries and hocs for more complex containers with recompose.

[doomsower]

Speaking of flexibility, just stumbled upon react-fns library, and they promote it lik "Flexible: Use render props and/or higher order components"

[quirm]

It would be great to get info whether graphql HOC will vanish in the near future or not. These Query and Mutation components are good for some use cases but they don't provide scalable and reusable code possibilities as the HOC alternative.

[HriBB]

But HOCs are still here: query, mutation and subscription.

Do they plan to remove them? I sure hope not.

@jbaxleyiii or one of the maintainers, can you please enlighten us 🙂

[haleykoike]

The HOCs are still in the codebase, but were recently removed from the default exports which implies that they are not meant to be used.
The PR comment from @peggyrayzis even says as much: https://github.com/apollographql/react-apollo/pull/1815#issue-176364778

[HriBB]

Ohh right. Why? Having both Components and HOCs available is super powerful. HOCs are useful when composing components with recompose. You can compose multiple mutations for example. And sometimes you just need a simple Query or a simple Button wrapped in a Mutation ...

Unless someone can convince me otherwise, I think having both is the best.

[veeramarni]

I think this issue needs to get more attention, graphql and other HOCs are really useful as described by @haleykoike. I don't find an easy alternate to migrate to new Query and Mutation Component.

[pho3nixf1re]

At the very least the documentation and exports should be restored.

[JuHwon]

I also think HOCs documentation are very important.
I was very confused by the removal of the HOCs in the documentation, since im obv not rewriting my whole code base the moment render prop copmonents are released

[HriBB]

I only use query HOC. It makes code more readable when using recompose. For mutations, I only use withApollo HOC, and call this.props.client.mutate() manually. I worst case scenario, we can create an external library to "polifill" query HOC, so no biggie ...

[marco-fp]

Is there a place to look up the documentation before this change in pattern was introduced?

For situations where there's already a large codebase using the HOCs it is essential to have somewhere to look for reference.

So far, this is the only place I've found that has it: https://web.archive.org/web/20171011015733/http://dev.apollodata.com/react/

[haleykoike]

@marco-fp This is what we've been using for reference:
https://medium.com/@newtmitch/i-built-and-hosted-apollo-graphql-legacy-documentation
https://s3.amazonaws.com/apollo-client-2.0.0/index.html

[rosskevin]

Hocs are in the codebase.

If you would like changes to the docs, please PR them. I'm here creating PRs and triaging issues through the holiday to try and do my part. If you think docs are important, please pitch in and create them. We all have a part to play here 👍

Closing - housekeeping