How to Consume a GraphQL API in Next.js with urql and next-urql
In this article, we will learn how to use urql to consume a GraphQL API in a Next.js SSR app.
Responses (1)

What is urql
?#
urql
is a lightweight, versatile and extensible GraphQL client for modern frontend apps, with support for React, Svelte, Vue and plain JavaScript. It was introduced as an alternative to existing GraphQL clients like Relay and Apollo. These GraphQL clients are largely similar when it comes to setup and use. In the next section, we will see how they compare with each other on various parameters.
Comparison: urql
vs Apollo vs Relay#
All three GraphQL clients provide standard features such as queries, mutations, caching and subscriptions, while only differing slightly in implementation.
urql
's defaults for configuration are slightly better than those for Apollo, and it has a lower entry barrier thanks to its thorough documentation and native support for features otherwise only available via third-party plugins. Additionally, urql
has a powerful caching mechanism offers both normalized and document caching via the @urql/exchange-graphcache
package.
urql
is built on the principle of having a lightweight core, extensible via middleware called exchanges. This makes it the smallest in bundle size as compared to the other options.
URQL | Apollo | Relay | |
Supported Frameworks | React, Svelte and Vue | Almost all front-end frameworks | React |
Usability | Easy setup, reasonable defaults | Easy setup, defaults usually need tweaking | Slightly more complicated to set up |
Extensibility | Extensible via exchanges | Extensible via links | Extensible via network layers |
Caching | Normalized and document caching | Normalized caching | Normalized caching |
Bundle Size | 5.9KB (7.1KB with bindings) | 32.9KB | 27.7KB (34.1KB with bindings) |
A full, detailed comparison of the clients by different categories of features can be found on the urql website.
Why use urql
with Next.js?#
Next.js is one of the most popular React-based frameworks, and urql
has first class native support for it via the next-urql
package.
Apollo and Relay do not have official plugins with support for Next.js which means the implementation might change between releases of the framework, and any app that uses it will have to be constantly maintained to keep up.
With next-urql
, most of the boilerplate involved in setting up urql
for Server-Side Rendering (SSR) with Next.js is already done for you. It provides convenience functions such as the withUrqlClient
HOC which enables your SSR pages to pre-fetch data via GraphQL queries.
Prerequisites#
Setting Up a Next.js and TypeScript Project#
Next.js requires Node to be pre-installed on your system. You can then scaffold a Next.js TypeScript app using the following command in your terminal/command prompt.
npx create-next-app@latest --typescript
Installing urql#
Once you have a skeleton app set up, you can install the dependencies required for urql
.
npm install --save urql graphql
graphql
is a peer dependency of urql
and provides the underlying GraphQL implementation. No additional type definitions are required since urql
is written in TypeScript.
Installing next-urql#
npm install --save next-urql react-is
next-urql
provides the Next.js bindings for urql
. react-is
is a peer dependency of next-urql
, required for react-ssr-prepass
to walk the component tree and pre-fetch any data required for rendering.
Setting up a GraphQL Client in Next.js with next-urql#
We can use the withUrqlClient
HOC to wrap our entire app in the urql
context.
import "../styles/globals.css";
import type { AppProps } from "next/app";
import { withUrqlClient } from "next-urql";
function App({ Component, pageProps }: AppProps) {
return <Component {...pageProps} />;
}
export default withUrqlClient(() => ({
url: "Your API URL",
}))(App);
This makes the urql
client and hooks usable in the rest of our app. The first parameter to withUrqlClient
is a function that returns a ClientOptions
object. This can be used to pass configuration into the urql
client instance, such as the API URL, custom fetch function, request policy and any additional middleware in the exchanges
property.
For this tutorial, we will use the GitHub GraphQL API. This API requires you to authenticate using a personal access token. You can follow the steps described here to create one after logging in with your GitHub account. We can then configure our urql
client to pass the token as part of the authorization header on each request to the API.
import "../styles/globals.css";
import type { AppProps } from "next/app";
import { withUrqlClient } from "next-urql";
function App({ Component, pageProps }: AppProps) {
return <Component {...pageProps} />;
}
const GITHUB_
please how can we do this with the new app folder and server components with next.js 13.2? thank you.