How to Consume a GraphQL API in Next.js with urql and next-urql

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.

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_