Overview

urql is a highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow. It's built to be both easy to use for newcomers to GraphQL, and extensible, to grow to support dynamic single-app applications and highly customized GraphQL infrastructure. In short, urql prioritizes usability and adaptability.

As you're adopting GraphQL, urql becomes your primary data layer and can handle content-heavy pages through "Document Caching" as well as dynamic and data-heavy apps through "Normalized Caching".

urql can be understood as a collection of connected parts and packages. When we only need to install a single package for our framework of choice. We're then able to declaratively send GraphQL requests to our API. All framework packages — like urql (for React), @urql/preact, @urql/svelte, and @urql/vue — wrap the core package, @urql/core, which we can imagine as the brain of urql with most of its logic. As we progress with implementing urql into our application, we're later able to extend it by adding "addon packages", which we call Exchanges

If at this point you're still unsure of whether to use urql, have a look at the Comparison page and check whether urql supports all features you're looking for.

Where to start

We have Getting Started guides for:

  • React/Preact covers how to work with the bindings for React/Preact.
  • Vue covers how to work with the bindings for Vue 3.
  • Svelte covers how to work with the bindings for Svelte.
  • Core Package covers the shared "core APIs" and how we can use them directly in Node.js or imperatively.

Each of these sections will walk you through the specific instructions for the framework bindings, including how to install and set them up, how to write queries, and how to send mutations.

Following the Documentation

This documentation is split into groups or sections that cover different levels of usage or areas of interest.

  • Basics is the section where we'll want to start learning about urql as it contains "Getting Started" guides for our framework of choice.
  • Architecture then explains more about how urql functions, what it's made up of, and covers the main aspects of the Client and exchanges.
  • Advanced covers all more uncommon use-cases and contains guides that we won't need immediately when we get started with urql.
  • Graphcache documents one of the most important addons to urql, which adds "Normalized Caching" support to the Client and enables more complex use-cases, smarter caching, and more dynamic apps to function.
  • Showcase aims to list users of urql, third-party packages, and other helpful resources, like tutorials and guides.
  • API contains a detailed documentation on each package's APIs. The documentation links to each of these as appropriate, but if we're unsure of how to use a utility or package, we can go here directly to look up how to use a specific API.

We hope you grow to love urql!