Getting started with urql

This chapter follows GraphQL clients compared.

Install urql 5 with its peer graphql package:

1
pnpm add urql graphql
2
pnpm add @urql/exchange-auth @urql/exchange-retry @urql/exchange-graphcache

urql 5 builds on @urql/core 6. The old defaultExchanges export is gone—compose cacheExchange and fetchExchange explicitly (plus any optional exchanges).

Create the client

1
import { cacheExchange, createClient, fetchExchange } from "urql";
2

3
export const client = createClient({
4
  url: import.meta.env.VITE_GRAPHQL_URL ?? "http://localhost:3000/graphql",
5
  exchanges: [cacheExchange, fetchExchange],
6
  fetchOptions: () => {
7
    const token = localStorage.getItem("token");
8
    return {
9
      headers: token ? { Authorization: `Bearer ${token}` } : {},
10
    };
11
  },
12
});

Wrap the app with Provider from urql:

1
import { Provider } from "urql";
2
import { client } from "./urql-client";
3

4
root.render(
5
  <Provider value={client}>
6
    <App />
7
  </Provider>,
8
);

Queries with useQuery

1
import { gql, useQuery } from "urql";
2

3
const BooksQuery = gql`
4
  query Books {
5
    books {
6
      id
7
      title
8
    }
9
  }
10
`;
11

12
export function BooksList() {
13
  const [{ data, fetching, error }] = useQuery({ query: BooksQuery });
14

15
  if (fetching) return <p>Loading…</p>;
16
  if (error) return <p>{error.message}</p>;
17
  return (
18
    <ul>
19
      {data?.books.map((b) => (
20
        <li key={b.id}>{b.title}</li>
21
      ))}
22
    </ul>
23
  );
24
}

Request policies and pause

Control caching behavior with requestPolicy:

Policy	Behavior
`cache-first`	Use cache if present, else network
`cache-only`	Never hit network
`network-only`	Skip cache read
`cache-and-network`	Return cache, then refresh

Set pause: true when variables are incomplete so urql skips the request until ready.

Call reexecuteQuery from the hook result to refetch manually.

Mutations with useMutation

1
import { gql, useMutation } from "urql";
2

3
const CreateBook = gql`
4
  mutation CreateBook($input: CreateBookInput!) {
5
    createBook(input: $input) {
6
      id
7
      title
8
    }
9
  }
10
`;
11

12
export function AddBook() {
13
  const [{ fetching }, execute] = useMutation(CreateBook);
14
  return (
15
    <button
16
      disabled={fetching}
17
      onClick={() => execute({ input: { title: "New" } })}
18
    >
19
      Add
20
    </button>
21
  );
22
}

The document cache updates for returned entities when IDs and __typename are present; complex graphs need Graphcache (next chapter).

Auth and retry exchanges

1
import { authExchange } from "@urql/exchange-auth";
2
import { retryExchange } from "@urql/exchange-retry";
3

4
createClient({
5
  exchanges: [
6
    cacheExchange,
7
    authExchange(async (utils) => ({
8
      addAuthToOperation(operation) {
9
        const token = localStorage.getItem("token");
10
        return token
11
          ? utils.appendHeaders(operation, { Authorization: `Bearer ${token}` })
12
          : operation;
13
      },
14
      refreshAuth: async () => {
15
        /* refresh token */
16
      },
17
      didAuthError: (err) => err.graphQLErrors.some((e) => e.extensions?.code === "UNAUTHENTICATED"),
18
    })),
19
    retryExchange({ maxNumberAttempts: 3 }),
20
    fetchExchange,
21
  ],
22
  url: "/graphql",
23
});

Order matters: auth and retry wrap fetch.

Subscriptions

Add subscriptionExchange with a graphql-ws client:

1
import { subscriptionExchange } from "urql";
2
import { createClient as createWsClient } from "graphql-ws";
3

4
const wsClient = createWsClient({ url: "ws://localhost:3000/graphql" });
5

6
subscriptionExchange({
7
  forwardSubscription: (operation) => ({
8
    subscribe: (sink) => ({
9
      unsubscribe: wsClient.subscribe(
10
        { query: operation.query, variables: operation.variables },
11
        sink,
12
      ),
13
    }),
14
  }),
15
});

Place it before fetchExchange in the exchange array.

Next: Typed operations with GraphQL Codegen.