What is urql

urql is a GraphQL client, exposed as a set of ReactJS components.

Why this exists

In my experience, existing solutions have been a bit heavy on the API side of things, and I see people getting discouraged or turned away from the magic that is GraphQL. This library aims to make GraphQL on the client side as simple as possible.

How it's different

React

urql is specifically for React. There have been no efforts made to abstract the core in order to work with other libraries. Usage with React was a priority from the get go, and it has been architected as such.

Render Props

Caching

urql takes a unique approach to caching. Many existing solutions normalize your data and parse your queries to try to invalidate cached data. I am not smart enough to implement this solution, and further, normalizing everything, on big datasets, can potentially lead to performance/memory issues.

urql takes a different approach. It takes your query signature and creates a hash, which it uses to cache the results of your query. It also adds __typename fields to both queries and mutations, and by default, will invalidate a cached query if it contains a type changed by a mutation. Further, handing control back to the users, it exposes a shouldInvalidate prop, which is a function that can be used to determine whether the cache is invalid based upon typenames, mutation response and your current data.

Install

npm install urql --save

Getting Started

If you want to get right down to business and try a working example of urql in action, check out this Code Sandbox:

The core of urql is three exports, Provider, Connect and Client. To get started, you simply create a Client instance, pass it to a Provider and then wrap any components you want to make queries or fire mutation from with a Connect component. We also provide a ConnectHOC higher order component, if you happen to not enjoy the absolutely amazing explicit nature of render props.

As you can see above, all that's required to get started is the url field on Client which tells us where your GraphQL API lives. After the client is created, and passed to the Provider that wraps your app, now you can wrap any component down in the tree with a Connect to start issuing queries.

Queries and mutations both have creation functions, which you can import. An urqlConnect component can take multiple queries, and multiple mutations. The render prop exposes the internal logic to any component you'd like to provide it to.

Lets start by defining a query and a mutation:

constTodoQuery=`query { todos { id text }}`;

HOLD UP FAM THIS IS IMPORTANT

It is absolutely necessary if you want this library to work properly, to create a valid mutation response. If you change a todo, return it. If you delete a todo, return it. If you add a todo, return it. If you don't return the thing that changed and file an issue, I'm going to screenshot this paragraph, paste it into the issue, and then drop my finger from a 3ft height onto the close button while making plane crash sounds.

loaded - This is like loading but it's false by default, and becomes true after the first time your query loads. This makes initial loading states easy and reduces flicker on subsequent fetch/refetches.

fetching - This is what you might commonly think of as loading. Any time a query or mutation is taking place, this puppy equals true, resolving to false when complete.

refetch - This is a method that you can use to manually refetch your query. You can skip the cache, hit the server and repopulate the cache by calling this like refetch({ skipCache: true }).

refreshAllFromCache - This is a method that you can use to manually refetch all queries from the cache.

data - This is where your data lives. Once the query returns, This would look like { todos: [...] }.

error - If there is an error returned when making the query, instead of data, you get this and you can handle it or show a refetch button or cry or whatever you wanna do.

Also, any mutations, because they are named, are also passed into this render prop.

As you can see above, the query accepts either a single query, or an array of queries. The mutation prop accepts an object, with the mutation names as keys.

So why do we use these query and mutation functions before passing them? Variables, thats why. If you wanted to pass a query with variables, you would construct it like so:

import { query } from'urql';
query(TodoQuery, { myVariable:5 });

Similarly, you can pass variables to your mutation. Mutation, however is a bit different, in the sense that it returns a function that you can call with a variable set:

import { mutation } from'urql';
mutation(AddTodo); // No initial variables// After you pass 'addTodo' from the render prop to a component:addTodo({ text:`I'm a variable!` });

Cache control

Normally in urql, the cache is aggressively invalidated based upon __typename, but if you want finer grained control over your cache, you can use the shouldInvalidate prop. It is a function, that returns a boolean, much like shouldComponentUpdate, which you can use to determine whether your data needs a refresh from the server. It gets called after every mutation:

data - The data that is local to your Connect component as a result of a query. ex: { todos: [] }

Using all or some of these arguments can give you the power to pretty accurately describe whether your connection has now been invalidated.

Custom Caches

The Client constructor accepts a cache setting where you can provide your own caching mechanism that will work with urql. By default, we use a local object store, but you can provide an adapter for whatever you want.

If you want to supply your own cache, you'll want to provide an object with the following keys:

API

Client

Options

An initial state for your cache if you are using the default cache. This probably won't get much play until SSR is implemented

cache

ICache

Instance of an ICache if you want to build your own custom one built with something like AsyncStorage. You can read more about how to create one of these above.

fetchOptions

object or () => object

Options provided to the internal fetch calls which can either be an object or a function if you want to provide dynamic values like a token header.

transformExchange

(IExchange, IClient) => IExchange

A function that receives the default "Exchange" and the client, and returns a new exchange. Use this to customise how the client handles GraphQL requests.

Description

Client is the constructor for your GraphQL client. It takes a configuration object as an argument, which is required. You can read more about the individual options above. Please note that providing a url property for your GraphQL API endpoint is required.

Example:

constclient=newClient({ url:'http://localhost:3000/graphql' });

With transformExchange you can completely customise how the urql client handles a GraphQL operation. Read more about this in the "Exchanges" section.

Provider

Provider is a ReactJS component that is used to provide the urql client throughout your application.

update - Takes a callback function with an argument shape of (store, key, value). The callback function is run against every cache entry, giving you the opportunity to update any given value based upon the context of the current data shape.

In addition to these, any specified mutations are also provided as their key in the mutation map. Mutations are functions that accept an object of variables as an argument and return a Promise which resolves to the data the mutation asked for.

ConnectHOC

(options: object | (props) => object) => (Component)

ConnectHOC is a higher order component that essentially does the same thing as the Connect component. All of Connect's props except for render are valid for the options object. Further, you can specify a function, which will provide the component's props and return a dynamic option set. The arguments you'd see in the render prop in Connect are passed automatically to the wrapped component.

mutation

CombinedError

CombinedError displays a list of all network and GraphQL errors that have occured during a GraphQL request.

No GraphQL errors will be present if a network error has occured

The following fields are present within a CombinedError:

Name

Value

Description

networkError

Error

Network error if fetch has failed

graphQLErrors

Error[]

GraphQL errors from the API response

reponse

FetchResponse

Raw Response instance

Exchanges

An “Exchange” is a function that accepts an operation and returns an observable with the GraphQL query’s result. Any operation, like queries or mutations, flow through the exchange and are processed by it.

The most important exchange is the httpExchange. It sends operations to your API and returns an observable with the actual result. urql comes with two more exchanges by default:

dedupExchange: Takes an exchange and returns a new one that deduplicates in-flight requests

cacheExchange: Reads query-operations from the cache and writes results to the cache

By default urql will create a default exchange using all three, which looks like this:

This means that by default urql will try to resolve queries from the cache (if skipCache is false), then deduplicate in-flight requests that have the same query and variables, and then send the operations that come through to your API endpoint. Lastly the result for queries will be written to the cache.

You can write your own exchanges if you wish to customise this behaviour. The client accepts the transformExchange function. This function receives the default exchange, as described above. So if you'd like to wrap the default exchange and do something custom, you can, or if you'd like to replace the default exchange you can just return an entirely different exchange.

The “Operations” that an exchange receives have the following properties:

Name

Value

Description

key

string

The cache key of an operation (query + variables hashed)

query

string

The GraphQL query string

variables

?object

Variables for the GraphQL query

operationName

string

The operation’s name, query or mutation

context

object

A dictionary of options

The context property can be used for any data, but the httpExchange in particular uses it to receive the url and fetchOptions, and the cacheExchange uses it to receive the skipCache flag.

The result that an exchange emits in an observable is like GraphQL’s ExecutionResult. It carries the data property, the error property that can be a CombinedError, and the typeNames property, which tells urql which parts of the cache to invalidate.

If you'd like to write your own exchange you could approach it like so:

TODO

Server Side Rendering

Client Side Resolvers

Cache update reactivity

Prefix all errors with "Did I do that?"

Prior Art

Apollo

This library wouldn't be possible without Apollo. Apollo was what made GraphQL click for me. I need to give big shout outs to folks like @stubailo, @jbaxleyiii and @peggyrayzis, without whom I wouldn't even know GraphQL. Enormous amounts of inspiration for this lib came from Apollo and its architecture.