Why the 2.0
The 2.0 version of ApolloClient provides a more customizable experience with GraphQL. It prioritizes features like custom execution chains (using Apollo Link) and custom stores while providing powerful defaults. It is an overall minor change to the API so you shouldn't have to change very much code in your current app at all!
The 1.0 version of Angular integration provides a better experience of using it in Angular. Thanks to changes to the API and the new way we create Apollo it is now possible to use it with anything from Angular's Dependency Injection.
2.* version of Apollo Client builds on the original principles of the project. For reference, those goals are:
- Universally compatible, so that Apollo works with any build setup, any GraphQL server, and any GraphQL schema.
- Simple to get started with, you can start loading data right away and learn about advanced features later.
- Inspectable and understandable, so that you can have great developer tools to understand exactly what is happening in your app.
- Built for interactive apps, so your users can make changes and see them reflected in the UI immediately.
- Small and flexible, so you don't get stuff you don't need
- Community driven, Apollo is driven by the community and serves a variety of use cases. Everything is planned and developed in the open.
Based on feedback from a wide variety of users, the
2.* version doubles down on being incrementally adoptable and flexible by allowing much stronger extension points. Customization of the client (i.e. data store, execution chain, etc) is a primary feature in the revised API. This version also take steps to reduce the overall size of the default client by 200% and provide the foundations for Apollo powering more of the application experience from development to production with client side state management.
The goal of the
2.0 launch is not to provide all of the new features that have been asked to be built in. Instead, the 2.0 makes a few key changes to both management of the code base (lerna / small modules) and the changes necessary to support custom stores and links fully. Apollo Client 2.0 is the jumping off point for user-land driven innovation (custom stores, custom links) and internal refactor (moving query manager into links, breaking apart the store / links into packages, etc).
The goal of the
1.0 launch is to improve the experience of using it in Angular.
One of the largest changes with the new version is the breaking apart of the monolith
apollo-client package into a few small, but isolated modules. This gives way more flexibility, but does require more packages to install.
To get started with the 2.0, you will change your imports from either
apollo-angular, or just
apollo-client to use the new packages. A typical upgrade looks like this:
A simple usage of Apollo Client upgrading to the 2.0 would look like this:
This is the most important part of migrating to 2.0. Two things to be explained.
We decided to move creation of Apollo Client closer to Angular Framework.
You no longer provide an instance of
Now it is being created when application bootstraps.
Thanks to the new way of configuring Apollo, it gains the access to Angular's Dependency Injection.
Just take the same options as you would normally use in ApolloClient's constructor and use them in
Apollo Client 2.0 by introducing Links has opened up the way to decide how to request data.
While designing 1.0 version of Apollo Angular we took advantage of both, ApolloLink library and new approach of configuring Apollo, and created a Link to fetch data through Angular's
Why we recommend it?
Besides many benefits of using
HttpClient (i.e. interceptors) you get the Server-Side Rendering for free. It also allows to use it in
NativeScript, without any additional work.
Why is that possible?
HttpLink and thanks to DI, the HttpLink does not care about which NgModule provides
HttpClient to an application since the API of
HttpClient is always the same.
Since everything was baked into the 1.0, custom configuration of the parts, like the network interface or cache, all were done on the constructor. With the 2.0, this is broken up slightly, and uneccessary configurations were removed. The following code snippet shows every possible option with the previous version and how to use it with the 2.0:
Note If you were using
customResolvers, the name of that has been changed to be
cacheResolvers to be more descriptive of what it does.
customResolvers will still be supported throughout the 2.0 though to be backwards compatible and ease the upgrade path.
If you have previously used
getInitialState for SSR, that API has been moved to the cache itself instead of on the client. You can read more about the recipe for server side rendering here. The upgrade path looks like this:
Network Middleware and Afterware
If you previously used
useAfter on the networkInterface from the 1.0 of Apollo Client, you will need to update to use Apollo Links as the new way to handle
*wares in the 2.0. Apollo Link provides a lot more power for
*ware features and more information is available here. A few examples of migrating custom
*ware methods to Apollo Links are shown below:
Afterware (error handling)
Afterware (data manipulation)
For more information on using Apollo Links, check out the link docs!;
The 2.0 moves away from using Redux as the caching layer in favor of Apollo maintaining its own store through the provided
cache passed when creating a client. This allows the new version to be more flexible around how data is cached, and opens the storage of data to many new avenues and view integrations. If you were previously using the Redux integration to do something like logging, you can now use an Apollo Link to log whenever a request is sent to the server. For example:
Ultimately we think the move off Redux will open the door for more powerful cache implementations and further performance gains. If you were using the Redux integration for other uses, please reach out or open an issue so we can help find a solution with the 2.0!
Query reducers have been finally removed in the 2.0, instead we recommend using the more flexible
update API instead of reducer.
Apollo 2.0 doesn't (currently) support passing observables as query variables. For now you can work around this by using
switchMap on the observable: