According to the docs,
urql is a GraphQL client that exposes a set of React components and hooks. It's built to be highly customisable and versatile so you can take it from getting started with your first GraphQL project all the way to building complex apps and experimenting with GraphQL clients.
Urql, pronounced as Urkel
, recently reached v1.0 a few months ago. Unlike Apollo, it is a minimalistic GraphQL Client. Urql was introduced as a response to Apollo's growing complexity of setup.
Comparison between Apollo and Urql
A detailed comparison between Apollo and Urql can be found below (credits to this original gist, edited for recent corrections):
Features | Apollo Client | Urql |
---|---|---|
Cache | Normalized objects | Hashing query + variables. Normalized Cache is WIP |
Batching | With apollo-link-batch-http (although it recommends deferring batching as long as possible) |
Doesn't have a first-party solution but allows to use Apollo's Link extensions |
Deduping | With apollo-link-dedup (enabled by default) |
With dedupExchange
|
Authentication | Supports adding options to the fetch client or changing the network layer altogether |
Supports adding options to the fetch client or changing the network layer altogether |
Pagination | First-party support with fetchMore, also provides several recipes | No first-party support, needs to implement a custom solution |
React Hooks | Officially supported as of v3.0 | First-party support |
Optimistic update |
mutate({ optimisticResponse }) (requires manipulating the cache if inserting new data) |
No support because of document based cache |
Local state | Support with @client directive |
No official support |
Refetch after mutation | mutate({ refetchQueries }) |
Needs to manually call a function obtained when performing the query |
Subscriptions | Supported | Supported |
Community | Vibrant, easy to find answers online, official chat, huge number of issues and PRs | Almost non-existent |
Documentation | Very thorough, with several tutorials and recipes | Comprehensive |
Setting up the GraphQL server
A GraphQL server has been made with Prisma 2 specifically for the purpose of this tutorial so make sure you clone it.
After cloning it, install the dependencies using yarn
. This will also run the postinstall
hook which runs prisma2 generate
that generates the photon and nexus-prisma types inside node_modules/@generated
folder.
Go ahead and start the server using:
$ yarn start
Open up http://localhost:4000 to play around with the GraphQL API.
Getting Started with Urql
Install urql
with the package manager of your choice:
$ yarn add urql
# or
$ npm install urql
urql
has a Provider
component similar to other libraries like react-redux
which manages state and data. You need to wrap your app with the Provider
component. This <Provider>
component holds the client
that is used to manage data, requests, the cache, and other things such that every component below it has an access to the client and it can query or mutate the data.
import React from 'react';
import { Provider, createClient } from 'urql';
const client = createClient({
url: "http://localhost:4000"
});
const App = () => (
<Provider value={client}>
{/* ... */}
</Provider>
);
export default App;
Querying data in Urql using Render Props or React Hooks
Let us query some GraphQL data using urql
's Query
component.
import React from 'react';
import { useQuery } from "urql";
const getPokemonData = `
query GetPokemonData($name: String!) {
pokemon(name: $name) {
id
number
name
attacks {
special {
id
name
damage
}
}
}
}
`;
export const ListPokemonDataQuery = ({ name = "Pikachu" }) => {
const [{ fetching, data, error }] = useQuery({
query: getPokemonData,
variables: { name }
});
if (fetching) {
return `Loading ${name}...`;
} else if (error) {
return `Oh no! Error: ${error}`;
}
const pokemon = data.pokemon[0];
return (
<>
<h1>
#{pokemon.number} {pokemon.name}
</h1>
<ul>
{pokemon.attacks.special.map(({ name, id, damage }) => (
<li key={name}>
#{id} {name} - {damage}
</li>
))}
</ul>
</>
);
};
The above Query
component sends getPokemonData
query with name
as a variable to the GraphQL API mentioned in url
property of createClient
.
Query
is a render prop which is nothing but a React component whose value is a function. This render prop gives us fetching
, data
and error
. fetching
returns a boolean whether the request is still being sent and is still loading. data
gives us the data returned by the GraphQL API and error
gives us whether we have any errors with the GraphQL API.
urql
also has a first-class Hooks support so we can also use useQuery
function.
If we rewrite the above example, it would look like:
import React from "react";
import { useQuery } from "urql";
const getPokemonData = `
query GetPokemonData($name: String!) {
pokemon(name: $name) {
id
number
name
attacks {
special {
id
name
damage
}
}
}
}
`;
export const ListPokemonDataHook = ({ name = "Pikachu" }) => {
const [{ fetching, data, error }] = useQuery({
query: getPokemonData,
variables: { name },
})
if (fetching) {
return `Loading ${name}...`;
} else if (error) {
return `Oh no! Error: ${error}`;
}
const pokemon = data.pokemon[0];
return (
<>
<h1>
#{pokemon.number} {pokemon.name}
</h1>
<ul>
{pokemon.attacks.special.map(({ name, id, damage }) => (
<li key={name}>
#{id} {name} - {damage}
</li>
))}
</ul>
</>
);
}
Notice, how the useQuery
hook simplifies the component structure. useQuery
works like any other React Hook as it takes in a value and returns a tuple. The value it takes in is a query and a variable name and it returns back a tuple containing fetching
, data
and error
. Everything else is just the same.
Mutating data in Urql using Render Props or React Hooks
Let us mutate some GraphQL data using urql
's Mutation
component.
import React, { useState } from 'react';
import { Mutation } from 'urql';
const addPokemon = `
mutation AddPokemon($number: Int!, $name: String!) {
addPokemon(data: {
number: $number,
name: $name
}) {
id
number
name
}
}
`
export const InsertPokemonMutation = () => {
const [name, setName] = useState('')
return (
<Mutation query={addPokemon}>
{({ fetching, data, error, executeMutation }) => {
return (
<>
{error && <div>Error: {JSON.stringify(error)}</div>}
<input value={name} onChange={e => setName(e.target.value)} />
<button onClick={() => {
if (name.trim() === "") return // return if input is empty
executeMutation({ name, number: Math.ceil(Math.random() * 1000) })
setName("") // clear the input
}}>
Add Pokemon
</button>
{data && (<div>
<br/>
Mutation successful:
<pre>{JSON.stringify(data, null, 2)}</pre>
</div>)}
</>
)
}}
</Mutation>
)
}
Mutation
component takes in a query and returns executeMutation
. executeMutation
is a function which takes in a variable name
and a random number
as stated in our addPokemon
query above and calls the Mutation
. If the mutation is unsuccessful then an error
is displayed. The render prop also gives you fetching
and data
if you want to do anything with it.
If we rewrite the above example using useMutation
hook then it would look like:
import React, { useState } from 'react';
import { useMutation } from 'urql';
const addPokemon = `
mutation AddPokemon($number: Int!, $name: String!) {
addPokemon(data: {
number: $number,
name: $name
}) {
id
number
name
}
}
`
export const InsertPokemonHook = () => {
const [name, setName] = useState('')
const [{ fetching, data, error }, executeMutation] = useMutation(addPokemon)
return (
<>
{error && <div>Error: {JSON.stringify(error)}</div>}
<input value={name} onChange={e => setName(e.target.value)} />
<button onClick={() => {
if (name.trim() === "") return
executeMutation({ name, number: Math.ceil(Math.random() * 1000) })
setName("")
}}>
Add Pokemon
</button>
{data && (<div>
<br/>
Mutation successful:
<pre>{JSON.stringify(data, null, 2)}</pre>
</div>)}
</>
)
}
useMutation
takes in the mutation addPokemon
and returns the mutations state (fetching
, data
and error
) and executeMutation
function in a tuple. executeMutation
is then called on a click of the button.
What are Exchanges in Urql
urql
has a concept of exchanges
. When a new Client()
is created you pass it a url
and fetchOptions
. But you can also pass it an exchanges
array. Exchanges are operation handlers. It receives client
and forward
function as an object and returns a function accepting a stream of operations and returning a stream of operation results (i.e. GraphQL results).
In other words, exchanges are handlers that fulfill our GraphQL requests. They're Input/Output streams, inputs being operations, outputs being results.
By default, urql
creates 3 different exchanges namely dedupExchange
, cacheExchange
and fetchExchange
.
dedupExchange
deduplicates pending operations. It eliminates duplicate operations waiting for a response as it wouldn't make sense to send the same operation twice at the same time.
cacheExchange
checks operations against the cache. Depending on the requestPolicy
cached results can be resolved instead and results from network requests are cached.
fetchExchange
sends an operation to the API and returns results.
When a new Client()
is created and no exchanges are passed to it then some are added automatically, which is the same as creating a new Client()
using the following exchanges:
import { Client, dedupExchange, cacheExchange, fetchExchange } from "urql";
const client = new Client({
url: "http://localhost:4000",
exchanges: [dedupExchange, cacheExchange, fetchExchange]
});
This can also be written as:
import { Client, defaultExchanges } from "urql";
const client = new Client({
url: "http://localhost:4000",
exchanges: defaultExchanges
});
Now that we know what are exchanges, lets learn about subscriptions.
Subscribing to data in Urql using Render Props or React Hooks
Go ahead and first install subscriptions-transport-ws
using yarn
:
$ yarn add subscriptions-transport-ws
To use subscriptions, we need to first add subscriptionExchange
to our new Client()
and also create a new SubscriptionClient()
using websocket protocol as follows:
import { SubscriptionClient } from "subscriptions-transport-ws";
import { Client, defaultExchanges, subscriptionExchange } from "urql";
const subscriptionClient = new SubscriptionClient(
"ws://localhost:4001/graphql",
{
reconnect: true,
timeout: 20000
}
);
const client = new Client({
url: "http://localhost:4000",
exchanges: [
...defaultExchanges,
subscriptionExchange({
forwardSubscription: operation => subscriptionClient.request(operation)
})
]
});
Now we can start using Subscription
component in our App:
import React from 'react'
import { Subscription } from 'urql'
const newPokemon = `
subscription PokemonSub {
newPokemon {
id
number
name
attacks {
special {
name
type
damage
}
}
}
}
`
const NewPokemon = () => (
<Subscription query={newPokemon}>
{({ fetching, data, error }) => {
if (fetching) {
return `Loading...`
} else if (error) {
return `Oh no! Error: ${error}`
}
const { newPokemon } = data
return (
<>
<h1>
#{newPokemon.number} {newPokemon.name}
</h1>
<ul>
{newPokemon.attacks.special.map(({ name, type, damage }) => (
<li key={name}>
{name} ({type}) - {damage}
</li>
))}
</ul>
</>
)
}}
</Subscription>
)
Subscription
component works in similar way to the Query
component. It can take in a query
and a variables
prop. It also has fetching
, data
and error
just like a Query
component. The data
and error
of the render props will change every time a new event is received by the server.
We can also use useSubscription
hook as follows:
import React from 'react';
import { useSubscription } from 'urql';
const newPokemon = `
subscription PokemonSub {
newPokemon {
id
number
name
attacks {
special {
name
type
damage
}
}
}
}
`
export const NewPokemonSubscriptionHook = () => {
const [{ fetching, data, error }] = useSubscription({ query: newPokemon }, (pokemons = [], res) => {
return [res.newPokemon, ...pokemons]
})
if (fetching) {
return `Loading...`
} else if (error) {
return `Oh no! Error: ${error}`
}
return (
<>
{data.map(pokemon => {
const { newPokemon } = pokemon
return (
<div key={newPokemon.number}>
<h1>
#{newPokemon.number} {newPokemon.name}
</h1>
<ul>
{newPokemon.attacks.special.map(({ name, type, damage }) => (
<li key={name}>
{name} ({type}) - {damage}
</li>
))}
</ul>
</div>
)
})}
</>
)
}
useSubscription
takes in the subscription newPokemon
and returns the subscriptions state (fetching
, data
and error
). Additionally, the second argument for useSubscription
can be an optional reducer function which works like Array.prototype.reduce. It receives the previous set of data that this function has returned or undefined
. As the second argument, it receives the event that has come in from the subscription. You can use this to accumulate the data over time, which is useful for a list for example.
Conclusion
In this tutorial, we learnt about URQL (Universal React Query Library) which is a blazing-fast GraphQL client, exposed as a set of ReactJS components. We then laid out the differences between Apollo and Urql.
We learnt about the Query
API, Mutation
API and Subscription
API provided by Urql. We also used the hooks useQuery
, useMutation
and useSubscription
to reduce the callback hell boilerplate unnecessarily created by Render Props.
We also learnt about Exchanges. Finally, we created a simple Pokemon application using Urql. Urql is a new piece of technology but it is mature enough to be used in production. Although, some things like Optimistic Updates do not yet work due to lack of cache normalization but its a work-in-progress and soon will be released.
Top comments (4)
Can you please post of screenshot of the demo?
Hey Mike, there's actually nothing but
<input>
's &<button>
's. Not really visually appealing so I went without screenshots otherwise I always put screenshots in every one of my posts.You can actually find the whole code here β github.com/deadcoder0904/graphql-a...
Clone it & install the dependencies & run the project to see it yourself.
I've also added instructions on how to start the server-side in the
server/
folder :)this is the kind of post that should have hundred thousands of likes. such a great example of using urql. π π π
What if I have multiple clients? How do I specify which client to use in the useQuery hook since we don't have a 'client' attr as we have in Apollo/client library?