Normalized caching with urql Graphcache

This chapter follows Typed operations with GraphQL Codegen.

The default cacheExchange stores operations by key. @urql/exchange-graphcache normalizes entities by __typename and id (or custom keys) so updating one mutation refreshes every query that referenced the same record.

Enable Graphcache

Replace cacheExchange with cacheExchange from @urql/exchange-graphcache:

1
import { cacheExchange } from "@urql/exchange-graphcache";
2
import { createClient, fetchExchange } from "urql";
3

4
export const client = createClient({
5
  url: "/graphql",
6
  exchanges: [cacheExchange({}), fetchExchange],
7
});

Pass schema (introspection JSON or codegen artifact) so Graphcache understands interfaces and unions when writing links.

Records and links

Graphcache maintains:

• Records — scalar fields keyed by entity ID (Book:1)
• Links — relations between records (Query.books → list of Book records)

When a query returns { id, __typename, title }, later mutations can patch Book:1 and all list queries see the new title without refetching.

keys and non-ID entities

Types without a natural ID need custom keys:

1
cacheExchange({
2
  keys: {
3
    SearchResult: () => null, // embedded, not normalized
4
    Product: (data) => data.sku as string,
5
  },
6
});

Returning null from keys embeds the object under its parent instead of a standalone record.

updates after mutations

Tell Graphcache how to merge mutation results:

1
cacheExchange({
2
  updates: {
3
    Mutation: {
4
      createBook(result, _args, cache) {
5
        cache.updateQuery({ query: BooksDocument }, (data) => {
6
          if (!data) return data;
7
          return { ...data, books: [...data.books, result.createBook] };
8
        });
9
      },
10
    },
11
  },
12
});

Prefer cache.updateQuery and cache.writeFragment over manual cache inspection.

Optimistic updates

1
useMutation(CreateBookDocument, {
2
  optimistic: {
3
    createBook: {
4
      id: "temp-id",
5
      __typename: "Book",
6
      title: "Draft",
7
    },
8
  },
9
});

Graphcache rolls back if the server errors. Match shape to the mutation selection set.

Resolvers and offline

resolvers on Graphcache can resolve fields locally when offline or while waiting for network—useful for read-through caches of computed fields. storage adapters persist the cache to IndexedDB for offline-first apps; replay queues mutations when connectivity returns.

Next: Evolving a GraphQL schema.