Apollo Client: The TypeScript GraphQL Client and Its Cache Model

What Apollo Client solves for GraphQL front ends

A GraphQL endpoint returns exactly the fields a query asked for, which means the same entity can arrive in several responses with different shapes. Fetching a user in a profile screen and again in a comment list produces two copies unless something reconciles them. Apollo Client exists to be that something: a client that issues queries and mutations over the network, stores results in a normalized cache keyed by type and id, and re-renders the components that depend on the affected fields.

The audience is JavaScript and TypeScript application teams. The README describes it as framework agnostic and lists React, Vue, Angular, Svelte and vanilla JavaScript, with React 19 support called out for Suspense, RSC and the Compiler. If your data layer is GraphQL and more than one component reads the same object, the cache is the feature you are actually buying. If your app makes two calls and displays the result once, the cache is overhead you will pay for in bundle size and configuration.

The normalized cache and the link chain

Two mechanisms carry most of the architecture. The first is the cache. Apollo Client stores objects by a normalized key, conventionally __typename plus id, so a User returned by one query and a User returned by another resolve to the same entry. Reads go through the cache first; a query whose data is fully present can be served without a network round trip depending on the fetch policy you set. Writes from mutations can update cached entities directly rather than forcing a refetch.

The second is the link chain. The package exports a set of links as separate entry points, visible in the package.json exports map: ./link/http, ./link/error, ./link/retry, ./link/ws, ./link/batch-http, ./link/persisted-queries, ./link/context, ./link/remove-typename, ./link/schema and others. A link takes an operation and returns an observable result, and links compose into a chain that terminates in a transport link such as HttpLink. Auth headers, retries, error handling and websocket subscriptions each become a link you insert rather than logic you scatter through components. That composability is the part of the design that ages best, because it keeps transport concerns out of the rendering layer.

The trade-off is that normalization is a policy, not a guarantee. Entities without a stable id, or with an id that changes between responses, need custom key fields or the cache will treat them as distinct objects and you will see stale or duplicated data. The README does not document these failure modes; the API reference linked from it is where type policies and key fields are described.

Installing Apollo Client and running a first query

The README gives a two-package install. The graphql package is a peer, not an optional extra, so it is installed alongside the client.

npm install @apollo/client graphql

After that, the README points to the Getting Started guide for setup and a first query rather than inlining the client construction. The repository does not show a complete React example in the README itself, so treat the docs link as the source of truth for the current API. For teams using an AI coding agent, the README also documents a skill install:

npx skills add apollographql/skills --skill apollo-client

That command adds Apollo Client specific guidance to the agent, which is useful when the agent would otherwise generate patterns from an older major version. One thing to check on your own setup: package.json sets "type": "module" and exposes conditional exports for core, cache, link and error subpaths, so the import path you use determines what gets bundled. Importing from the root pulls in more than importing from ./link/http.

Where Apollo Client is the wrong choice

The clearest mismatch is an application that is not GraphQL-first. Apollo Client speaks GraphQL; wrapping a REST API in a thin GraphQL layer so you can use the client inverts the cost, and you inherit a schema, a resolver layer and a cache to maintain for the sake of one transport. A plain fetch wrapper or a query library with a simpler cache will be less code.

A second case is a bundle-sensitive surface where the cache is never exercised. The repository ships a .size-limit.cjs and .size-limits.json, which tells you the maintainers track bundle size as a first-class concern, but tracked does not mean small. If you only need to send a mutation and read the response, the normalized cache and the link abstraction are weight you will not recover.

A third is teams that will not configure the cache. Default normalization handles the common case of objects with stable ids. The moment your data has lists of items without ids, paginated fields, or server data that changes shape between queries, you are writing merge functions and key fields. That work is real and it lands on whoever owns the data layer.

Apollo Client against a minimal client such as graphql-request

The honest alternative for many teams is not another full client but a minimal one. graphql-request is a small client that sends a query and returns the parsed JSON with types, and stops there. There is no normalized cache, no link chain, no reactive store, and no framework bindings; you manage loading and error state yourself, usually with whatever data-fetching library you already use.

The difference in approach matters more than the feature list. Apollo Client owns your application state: it decides when a component re-renders because a cached field changed, and it holds the single source of truth for server data. graphql-request owns nothing; it is a typed transport, and state lives wherever you put it. If your team already runs a separate state library and wants GraphQL to be just another data source, the minimal client composes more cleanly. If overlapping reads of the same entity are common and you want them reconciled automatically, that reconciliation is precisely what you would otherwise rebuild on top of graphql-request, and it is what Apollo Client ships.

Maintenance cadence, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-19. Recent releases are close together: @apollo/[email protected] on 2026-09-18, 4.3.0 on 2026-09-11, and @apollo/[email protected] on 2026-09-11. The project is maintained by named maintainers listed in the README, with a public roadmap in ROADMAP.md and a changeset directory that suggests releases are assembled from changeset entries.

The upgrade cost deserves attention before you adopt. The README's Versioning Policy section states that while Apollo Client follows SemVer, it may introduce changes such as changing transpilation targets, updating dependencies, or dropping support for older dependency versions in minor releases. That is a broader definition of a minor release than many teams assume, and it means a 4.x to 4.y upgrade can require build or dependency work even without a breaking API change. Budget for reading the changelog on minor bumps, not just majors.

On licensing, package.json declares MIT. That is a permissive licence, but nothing here is legal advice; if you redistribute the client or bundle it into a product with its own terms, read the LICENSE file in the repository and your own counsel's guidance.

Editorial conclusion

Adopt Apollo Client when your app is GraphQL-first, spans several components that read overlapping data, and you want one normalized cache instead of hand-rolled fetch state; the framework-agnostic core and the React hooks are the strongest reasons. Do not adopt it for a single REST endpoint wrapped in a thin GraphQL layer, or if you will not invest in cache configuration, because default normalization is where most surprise comes from. Before committing, verify three things against the repository: that @apollo/[email protected] and the matching graphql peer install cleanly in your bundler, that the cache type policies you need are expressible in the documented API, and that the VERSIONING_POLICY.md note about minor releases changing transpilation targets and dependencies is acceptable to your upgrade cadence.

Frequently asked questions

Official sources

1. apollographql/apollo-client on GitHub
2. License: MIT
3. Project website
4. README
5. Releases