/web-data-fetching-graphql-urql

name: web-data-fetching-graphql-urql
description: URQL GraphQL client patterns — the exchange pipeline, document and normalized caching, queries, mutations, subscriptions, and authentication

URQL Patterns

> **Quick Guide:** URQL is a small core plus a pipeline of exchanges, and almost every configuration > question is really a question about that pipeline's order — synchronous exchanges before > asynchronous ones, error handlers before what they catch, `fetchExchange` last. Caching is > document-based by default, keyed on the query and its variables; normalized caching is an opt-in > exchange. Hooks return a `[result, execute]` tuple, and the loading flag is `fetching`.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — client and provider, `useQuery`, mutations, error handling, per-query context
• [examples/exchanges.md](examples/exchanges.md) — the full pipeline, Graphcache config, auth with refresh, retry, custom exchanges
• [examples/subscriptions.md](examples/subscriptions.md) — websocket setup, accumulating events, presence, cache updates from a subscription
• [examples/v6-features.md](examples/v6-features.md) — the GET default, `preferGetMethod`, and the v4 → v6 migration steps
• [reference.md](reference.md) — request policy and cache method tables, `CombinedError` shape, exchange catalogue

---

Which path applies

• **Document caching** — the default `cacheExchange` from `urql`. A query plus its variables is one

cache entry, and a mutation invalidates every entry whose result shared a `__typename` with it. Nothing to configure, and no way to edit the cache by hand.

• **Normalized caching** — the `cacheExchange` from `@urql/exchange-graphcache`, replacing the

default one. Entities are stored once by key, so `keys`, `updates`, `resolvers` and `optimistic` become available and mutations can edit the cache precisely. Adds roughly 8KB.

Start with the document cache. Move to Graphcache when a mutation needs to change a list the server did not return, or when you want optimistic updates.

---

<critical_requirements>

Before writing URQL code

**Order the exchanges: error handling, then synchronous, then asynchronous, with `fetchExchange` last.** An operation passes through them in array order, so a cache placed after a network exchange never sees a request, and an error handler placed after `authExchange` never sees a failed refresh.

**Put `__typename` in every optimistic response, along with every field a query reads.** Graphcache normalizes on `__typename` plus the key, and a field the optimistic object omits is a field the watching query cannot render.

**Set `preferGetMethod` to what the server accepts.** From v6 the client sends queries under 2048 characters as GET; `false` forces POST for everything, and `"force"` sends GET regardless of length.

</critical_requirements>

---

**Auto-detection:** `urql`, `@urql/core`, `@urql/exchange-graphcache`, `cacheExchange`, `fetchExchange`, `subscriptionExchange`, `mapExchange`, `ssrExchange`, `authExchange`, `retryExchange`, `useQuery`, `useMutation`, `useSubscription`, `requestPolicy`, `preferGetMethod`, `reexecuteQuery`, `CombinedError`, `wonka`

**Applies to:**

• The exchange pipeline, its order, and writing an exchange
• Document caching and normalized caching through Graphcache
• Queries, mutations, optimistic updates and cache edits after a write
• Real-time data over a subscription exchange
• Authentication with token refresh, and retry policy

**Handled elsewhere:**

• APIs addressed over REST — this client speaks one query language
• Designing the schema and its resolvers; this skill consumes a schema
• Client state that corresponds to no server field
• Where errors are shipped once `mapExchange` has caught them

---

<philosophy>

Philosophy

The client itself does almost nothing: it turns a hook call into an operation and pushes it into a stream. Everything that looks like a feature — caching, auth, retries, deduplication, subscriptions, server rendering — is an exchange sitting in that stream, and every exchange sees the operation on the way out and the result on the way back.

Two things follow. Behaviour is added by installing an exchange rather than by configuring the client, so a project pays only for what it installs. And order is semantic rather than cosmetic: an exchange can only act on what has already reached it.

</philosophy>

---

<patterns>

Core patterns

Pattern 1: Client setup

import { Client, cacheExchange, fetchExchange } from "urql";

const client = new Client({
  url: GRAPHQL_ENDPOINT,
  exchanges: [cacheExchange, fetchExchange],
  requestPolicy: "cache-first",
});

`<Provider value={client}>` above the tree is what the hooks read; without it they throw at the first render rather than falling back to anything.

Full code: [examples/core.md](examples/core.md)

---

Pattern 2: Queries

const [result, reexecuteQuery] = useQuery<UsersData, UsersVariables>({
  query: USERS_QUERY,
  variables: { limit: DEFAULT_PAGE_SIZE },
  requestPolicy: "cache-and-network",
});

const { data, fetching, error, stale } = result;

if (fetching && !data) return <Skeleton />;
if (error && !data) return <Error message={error.message} />;

`fetching` is true for the first load and for every background refresh, so `fetching && !data` is what distinguishes them. `stale` marks cached data being revalidated — an "updating" hint rather than a spinner. `pause: !userId` holds a query back until its variables are real.

Default policy is `cache-first`; `cache-and-network` is the stale-while-revalidate one. The full table is in [reference.md](reference.md).

Full code: [examples/core.md](examples/core.md)

---

Pattern 3: Mutations

const [result, executeMutation] = useMutation<CreatePostData>(CREATE_POST);

const response = await executeMutation({ input });
if (response.error) return;

The execute function returns a promise c