ROADMAP.md

Apollo Client Roadmap

Product vision

Apollo Client is a framework for consuming a data graph and binding it to a user interface. It is written in TypeScript, designed for use with React, and integrates seamlessly with the rest of the Apollo GraphQL platform. Apollo Client is easy to use, thoroughly documented, incrementally adoptable, and scalable to the needs of enterprise-grade applications. Our goal is to make Apollo Client not only the best way to use GraphQL, but also the the best way to manage data for React apps. Apollo Client ships with a first-class set of developer tools, including a CLI, VS Code extension, and in-browser debugging tools.

Apollo Client 3.0

Completion date: Full RC available end of October 2019

At a high level, the next major version of Apollo Client (roughly referred to as Apollo Client 3) aims to:

• Prune outdated and overlapping API surface areas
• Redesign the core caching layer
• Simplify the product's packaging

Goals

• Only one package is required to install and use all core Apollo Client features (including React integration and networking).

  • This makes documentation easier to understand and helps developers get to their first "feature shipped" without having to learn multiple packages.
  • This also helps teams customize their build of Apollo Client for advanced usage.

• The default @apollo/client bundle is 60kb minified (but not gzipped) if using no build tools (less if using build tools).

  • This is roughly half the size of the current libraries and half the size of react + react-dom.
  • This includes all packages needed for a full, out-of-the-box Apollo Client experience (Apollo Client core with cache and utilities, React hooks integration, and networking). It will be possible to enable/disable features to reduce the overall bundle size.

• While simulating a 4x CPU slowdown in Chrome, Apollo Client fetch-and-cache operations complete in 16ms or less to account for repaint frame rates.

  • This is a rough approximation of mid-range mobile devices.

• The new EntityCache (name TBD) furthers the ideas started with federation to take advantage of a principled datagraph.

  • The EntityCache uses entities and keys to know object identity for selective normalization and better performance.
  • It works well for server-side rendering and offline apps, including error storage and priority rendering for prefetched work.
  • Its configuration can be generated by the CLI but is clear and straightforward enough to be created and edited manually.

• Refreshed and redesigned documentation that helps teams be productive throughout their adoption of Apollo Client.

  • Features a new getting-started experience to help React engineers be productive from day one.
  • Explains the architecture and cache design more clearly as teams adopt more advanced features.

How we get there

Apollo Client 3 will be a rewrite-in-place of the Apollo Client project, while we support and maintain Apollo Client 2.x in a reduced manner. Because we are moving to a new package name and structure, we will begin an alpha cycle as soon as the new core is usable by production teams. This will allow us to get concrete performance numbers from real-world usage.

Apollo Client 3 will feature simplified packaging for easier use and smaller bundles, along with a new cache implementation with more control and better performance. The work to accomplish these goals is grouped as follows:

• Simplified packaging for easier use and smaller bundles:

  • Two packages (down from the current ~15 packages): @apollo/client and @apollo/graphql
  • Separate reduced and focused bundles to allow applications to use only the parts of Apollo Client they want to (e.g. @apollo/client/core for just the AC core + cache)
  • Further bundle size reductions by pruning apollo-utilities and other API cruft needed to support the generic APIs currently supported
  • Reduction of mental overhead for teams by providing a single-package, out-of-the-box experience for React. More advanced teams use the same package by building their own version if needed using file imports
    • This follows the same pattern that @apollo/graphql and @apollo/server will use.
  • Pruning of the client API to reduce confusion, increase performance, and thin bundle size
    • Remove watchQuery in favor of a single query method that returns a watchable result stream.
    • Remove the custom cache implementation entry point in favor of a simplified config API that can be generated by build tools.
    • Remove multiple confusing and overlapping "store reset" APIs.
    • Remove costly deep equality checks in favor of immutable structures.
  • Avoid making subscriptions part of the default Apollo Client build, instead making them importable.
  • Instead of using GraphQL ASTs, power the cache with an efficient "IR" (intermediate representation) that can be understood at both runtime and build time for teams that want to maximize performance.
    • This enables teams to completely remove graphql-js and startup parsing work from the bundle and send less data over the wire with a predefined set of cache actions per operation/fragment.

• New cache implementation with more control and better performance:

  • Improve performance of pre-rendered datasets done from SSR or offline storage so that the UI is painted immediately before the data is linked in the cache. This removes blocking thread work for teams that have already fetched the data leading to faster paints.
  • Support custom normalization through a new config API. Custom normalization allows for parts of a response to skip costly normalization when it is not needed by the UI. This will use the concept of Entities from Apollo Server and allow for teams to tailor performance of the cache to their specific UI needs. Put another way, the new cache will support both the normalization and de-normalization of stored data.
    • This allows teams with very large datasets to opt out of more expensive work resulting in much faster reads from the cache.
    • It also makes for a more predictable set of actions for working with the cache and enables more possibilities around using fragments directly.
  • Automatically garbage collect orphaned entities in the cache to reduce cache memory footprint and "unbound growth" problems for long-running applications
  • Properly support cache eviction so that mutations can clean up entities in the cache and data that is deemed "too old" can be pruned from the cache. This allows long-running applications to keep the cache small and snappy.
  • Add support for storing errors in the cache. This is critical for offline and SSR apps that might encounter errors that are rendered into the UI.

• Completely re-architected documentation site explaining the value of Apollo Client:

  • Features a new getting-started section targeted for professional React developers to be productive from day one
  • Better explains the architecture of the client and its core features
  • Includes in-depth guidelines for running in production, with build tooling (CLI/TypeScript) and better recipes around common actions like auth

After Apollo Client 3.0

Although we don’t have concrete timelines for the next set of work, we think these are the next challenges to tackle, ordered by priority:

• Redesign Apollo Client's network layer
  • We're planning out a simplified but flexible network layer that removes Observable's from the ApolloLink API in favor of language primitives. This will simplify custom building, trim bundles, and better support multiple responses.
• Supporting @defer and @stream
• Fragment-based API for component isolation
• Improved local state API
• Cache segmenting