kitten.sh
1---
2title: Graphcache
3order: 5
4---
5
6# Graphcache
7
8In `urql`, caching is fully configurable via [exchanges](../architecture.md), and the default
9`cacheExchange` in `urql` offers a ["Document Cache"](../basics/document-caching.md), which is
10usually enough for sites that heavily rely on static content. However as an app grows more
11complex it's likely that the data and state that `urql` manages, will also grow more complex and
12introduce interdependencies between data.
13
14To solve this problem most GraphQL clients resort to caching data in a normalized format, similar to
15how [data is often structured in
16Redux.](https://redux.js.org/recipes/structuring-reducers/normalizing-state-shape/)
17
18In `urql`, normalized caching is an opt-in feature, which is provided by the
19`@urql/exchange-graphcache` package, _Graphcache_ for short.
20
21## Features
22
23The following pages introduce different features in _Graphcache_, which together make it a compelling
24alternative to the standard [document cache](../basics/document-caching.md) that `urql` uses by
25default.
26
27- 🔁 [**Fully reactive, normalized caching.**](./normalized-caching.md) _Graphcache_ stores data in
28 a normalized data structure. Query, mutation and subscription results may update one another if
29 they share data, and the app will rerender or refetch data accordingly. This often allows your app
30 to make fewer API requests, since data may already be in the cache.
31- 💾 [**Custom cache resolvers**](./local-resolvers.md) Since all queries are fully resolved in the
32 cache before and after they're sent, you can add custom resolvers that enable you to format data,
33 implement pagination, or implement cache redirects.
34- 💭 [**Subscription and Mutation updates**](./cache-updates.md) You can implement update functions
35 that tell _Graphcache_ how to update its data after a mutation has been executed, or whenever a
36 subscription sends a new event. This allows the cache to reactively update itself without queries
37 having to perform a refetch.
38- 🏃 [**Optimistic mutation updates**](./cache-updates.md) When implemented, optimistic updates can
39 provide the data that the GraphQL API is expected to send back before the request succeeds, which
40 allows the app to instantly render an update while the GraphQL mutation is executed in the
41 background.
42- 🧠 [**Opt-in schema awareness**](./schema-awareness.md) _Graphcache_ also optionally accepts your
43 entire schema, which allows it to resolve _partial data_ before making a request to the GraphQL
44 API, allowing an app to render everything that's cached before receiving all missing data. It also
45 allows _Graphcache_ to output more helpful warnings and to handle interfaces and enums correctly
46 without heuristics.
47- 📡 [**Offline support**](./offline.md) _Graphcache_ can persist and rehydrate its entire state,
48 allowing an offline application to be built that is able to execute queries against the cache
49 although the device is offline.
50- 🐛 [**Errors and warnings**](./errors.md). All potential errors are documented with information on
51 how you may be able to fix them.
52
53## Installation and Setup
54
55We can add _Graphcache_ by installing the `@urql/exchange-graphcache` package.
56Using the package won't increase your bundle size by as much as platforms like
57[Bundlephobia](https://bundlephobia.com/result?p=@urql/exchange-graphcache) may suggest, since it
58shares the dependency on `wonka` and `@urql/core` with the framework bindings package, e.g. `urql`
59or `@urql/preact`, that you're already using.
60
61```sh
62yarn add @urql/exchange-graphcache
63# or
64npm install --save @urql/exchange-graphcache
65```
66
67The package exports the `cacheExchange` which replaces the default `cacheExchange` in `@urql/core`.
68This new `cacheExchange` must be instantiated using some options, which are used to customise
69_Graphcache_ as introduced in the ["Features" section above.](#features) However, you can get started
70without passing any options.
71
72```js
73import { Client, fetchExchange } from 'urql';
74import { cacheExchange } from '@urql/exchange-graphcache';
75
76const client = new Client({
77 url: 'http://localhost:3000/graphql',
78 exchanges: [cacheExchange({}), fetchExchange],
79});
80```
81
82This will automatically enable normalized caching, and you may find that in a lot of cases,
83_Graphcache_ already does what you'd expect it to do without any additional configuration. We'll
84explore how to customize and set up different parts of _Graphcache_ on the following pages.
85
86[Read more about "Normalized Caching" on the next page.](./normalized-caching.md)