urql
By Formidable and the urql community
urql is a lightweight GraphQL client library for JavaScript applications, designed as a smaller and more extensible alternative to Apollo Client, providing core query, mutation, and subscription capabilities out of the box while pushing…
Definition
urql is a lightweight GraphQL client library for JavaScript applications, designed as a smaller and more extensible alternative to Apollo Client, providing core query, mutation, and subscription capabilities out of the box while pushing more advanced caching and normalization behavior into optional exchange plugins that developers add only when needed. It ships official bindings for React, Vue, Svelte, and Preact.
Overview
urql was created in response to a perception that existing GraphQL clients, particularly Apollo Client, had grown large and opinionated by default, bundling features like a fully normalized cache and extensive local state management even for applications that did not need them. Its designers wanted a client that started minimal and let teams opt into more sophisticated behavior only when their application's complexity justified the added weight and configuration surface. Mechanically, urql is built around a core client combined with a pipeline of composable functions called exchanges, each responsible for one piece of request handling such as deduplication, caching, or error handling, chained together in a configurable order similar to middleware in an HTTP server. The default cache exchange performs simple document caching, storing whole query results keyed by the query and its variables, which is far less complex than a normalized cache but sufficient for many applications. Developers who need normalized, entity-level caching similar to Apollo Client's default behavior can add the `@urql/exchange-graphcache` package, which turns on that behavior as an explicit opt-in rather than a default. urql differs from Apollo Client primarily in this exchange-based extensibility model and its smaller default bundle size, since teams pay the cost of normalized caching only if they choose to add it. It differs from Relay by not requiring any build-time compiler step or strict fragment colocation conventions, making it considerably easier to adopt incrementally into an existing project without changing tooling. This positions urql as a middle ground: more capable and GraphQL-aware than a generic data-fetching library, but far less opinionated and heavyweight than Relay. In practice, teams choose urql when they want GraphQL-specific conveniences, like automatic request deduplication and straightforward query and mutation hooks, without committing to Apollo Client's full feature set and cache complexity from the outset. Its React bindings, `useQuery`, `useMutation`, and `useSubscription`, closely mirror Apollo Client's API shape, which eases migration in either direction. Because exchanges are composable, teams can also write custom exchanges for authentication token refresh, request logging, or persisted queries without needing to fork the library. The main trade-off with urql is that its default caching behavior is simpler than Apollo Client's normalized cache, meaning applications with complex, deeply interrelated data may see less automatic UI consistency out of the box unless they add the graphcache exchange, which reintroduces much of the configuration complexity urql was designed to avoid by default. Its ecosystem and community size are also smaller than Apollo Client's, meaning fewer third-party integrations and community resources are available. Teams with straightforward data needs and a preference for a lean bundle benefit most from urql's minimal-by-default design.
Key Features
- Lightweight core client with a smaller default bundle size than alternatives
- Composable exchange pipeline for customizing request handling behavior
- Automatic request deduplication built into the default exchange chain
- Optional normalized caching via the separate graphcache exchange package
- Official bindings for React, Vue, Svelte, and Preact
- No build-time compiler step required, unlike Relay
- Support for GraphQL subscriptions through configurable exchanges
- API shape closely mirroring Apollo Client for easier migration