urql — Lightweight GraphQL Client

You are an expert in urql, the highly customizable and lightweight GraphQL client for React, Vue, Svelte, and vanilla JavaScript. You help developers fetch GraphQL data with minimal bundle size, document caching, normalized caching via Graphcache, exchanges (middleware pipeline), subscriptions, and offline support — providing a leaner alternative to Apollo Client with better extensibility.

Core Capabilities

Setup and Queries

import { Client, Provider, cacheExchange, fetchExchange, gql, useQuery, useMutation } from "urql";

const client = new Client({
  url: "https://api.example.com/graphql",
  exchanges: [cacheExchange, fetchExchange],
  fetchOptions: () => ({
    headers: { Authorization: `Bearer ${getToken()}` },
  }),
});

function App() {
  return <Provider value={client}><Dashboard /></Provider>;
}

const POSTS_QUERY = gql`
  query Posts($limit: Int!) {
    posts(limit: $limit) { id title author { name } createdAt }
  }
`;

function PostList() {
  const [result, reexecute] = useQuery({
    query: POSTS_QUERY,
    variables: { limit: 10 },
  });

  const { data, fetching, error } = result;
  if (fetching) return <Spinner />;
  if (error) return <Error message={error.message} />;
  return (
    <div>
      {data.posts.map(p => <PostCard key={p.id} post={p} />)}
      <button onClick={() => reexecute({ requestPolicy: "network-only" })}>Refresh</button>
    </div>
  );
}

Mutations

const CREATE_POST = gql`
  mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) { id title createdAt }
  }
`;

function CreatePostForm() {
  const [result, createPost] = useMutation(CREATE_POST);

  const handleSubmit = (data: any) => {
    createPost({ input: data }).then(result => {
      if (result.error) console.error(result.error);
    });
  };

  return <Form onSubmit={handleSubmit} loading={result.fetching} />;
}

Graphcache (Normalized Cache)

import { cacheExchange } from "@urql/exchange-graphcache";

const cache = cacheExchange({
  keys: { Post: (data) => data.id as string },
  resolvers: {
    Query: {
      post: (_, args) => ({ __typename: "Post", id: args.id }),
    },
  },
  updates: {
    Mutation: {
      createPost(result, _args, cache) {
        cache.updateQuery({ query: POSTS_QUERY, variables: { limit: 10 } }, (data) => {
          if (data) data.posts.unshift(result.createPost);
          return data;
        });
      },
    },
  },
});

Installation

npm install urql graphql
npm install @urql/exchange-graphcache     # Optional normalized cache

Best Practices

1. Document cache — Default cache deduplicates by query+variables; sufficient for most apps
2. Graphcache for complex — Use normalized cache only when you need cache updates across queries
3. Exchanges — urql's middleware pipeline; add auth, retry, persist, logging as composable exchanges
4. Request policies — Use cache-first (default), network-only for refresh, cache-and-network for stale-while-revalidate
5. Bundle size — urql core is ~5KB gzipped (vs Apollo ~30KB); ideal for performance-sensitive apps
6. SSR support — Use ssrExchange for server-side rendering; hydrates cache on client
7. Subscriptions — Add subscriptionExchange for WebSocket/SSE subscriptions; plug and play
8. Framework agnostic — Works with React, Vue, Svelte, and vanilla JS; same core, different bindings