URQL — Lightweight Extensible GraphQL Client for React and Beyond

Introduction

GraphQL clients can become complex when they try to solve every caching and state management problem internally. URQL takes a different approach by providing a small, focused core with a plugin system called exchanges that lets you add exactly the capabilities you need — from simple document caching to normalized caching and offline support — without carrying features you do not use.

What URQL Does

• Sends GraphQL queries, mutations, and subscriptions with a minimal API surface
• Provides React hooks (useQuery, useMutation, useSubscription) for declarative data fetching
• Supports Vue, Svelte, and vanilla JavaScript through dedicated bindings
• Uses an exchange pipeline to compose caching, authentication, retries, and other behaviors
• Includes a normalized cache (Graphcache) for applications that need fine-grained cache updates

Architecture Overview

URQL is built around a stream-based exchange pipeline inspired by middleware patterns. Each operation (query, mutation, subscription) flows through a chain of exchanges that can intercept, modify, cache, or forward it. The default setup includes a document cache exchange (which caches by query and variables) and a fetch exchange (which sends requests to the server). More advanced setups swap in Graphcache for normalized caching, add retry or auth exchanges, or implement custom exchanges for logging and error tracking. This modular design means the client only includes the code paths your application actually uses, keeping the bundle size small.

Self-Hosting & Configuration

• Install urql and graphql: npm install urql graphql
• Create a Client with your GraphQL endpoint URL and a list of exchanges
• Wrap your React app with the Provider component passing the client
• Add @urql/exchange-graphcache for normalized caching when needed
• Use @urql/exchange-auth to handle token refresh and authentication headers

Key Features

• Small bundle size starts under 8 KB gzipped with the default document cache
• Exchange architecture lets you compose exactly the features you need as plugins
• Graphcache provides normalized caching with automatic cache updates after mutations
• First-class support for React, Vue, Svelte, and vanilla JavaScript from the same core
• Server-side rendering support with built-in data hydration utilities

Comparison with Similar Tools

• Apollo Client — Full-featured but heavier; URQL is smaller and more modular with its exchange system
• Relay — Compiler-driven and opinionated; URQL offers more flexibility with less setup overhead
• graphql-request — Minimal fetch wrapper without caching; URQL adds caching and framework bindings
• TanStack Query — REST-focused data fetching; URQL is purpose-built for GraphQL with schema-aware caching
• SWR — React hooks for REST APIs; URQL understands GraphQL operations natively for smarter caching

FAQ

Q: When should I choose URQL over Apollo Client? A: Choose URQL when you want a smaller bundle, simpler API, and the ability to add features incrementally through exchanges rather than configuring a monolithic client.

Q: Does URQL support subscriptions? A: Yes. URQL supports GraphQL subscriptions over WebSocket using the subscriptionExchange with any WebSocket client library.

Q: What is Graphcache and when do I need it? A: Graphcache is URQL's normalized cache. Use it when your application needs automatic cache updates after mutations or when multiple queries share overlapping data.

Q: Can I use URQL without React? A: Yes. URQL provides bindings for Vue, Svelte, and a vanilla JavaScript core client that works in any environment.

Sources

• https://github.com/urql-graphql/urql
• https://urql.dev/