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.

 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 

. 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.

All three GraphQL clients provide standard features such as queries, mutations, caching and subscriptions, while only differing slightly in implementation. 

'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, 

 has a powerful caching mechanism offers both normalized and document caching via the 

 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 

Next.js is one of the most popular React-based frameworks, and 

 has first class native support for it via the 

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.

, most of the boilerplate involved in setting up 

 for Server-Side Rendering (SSR) with Next.js is already done for you. It provides convenience functions such as the 

 HOC which enables your SSR pages to pre-fetch data via GraphQL queries.

Setting Up a Next.js and TypeScript Project

 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.

Once you have a skeleton app set up, you can install the dependencies required for 

 and provides the underlying GraphQL implementation. No additional type definitions are required since 

 to walk the component tree and pre-fetch any data required for rendering.

Setting up a GraphQL Client in Next.js with next-urql

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);


 client and hooks usable in the rest of our app. The first parameter to 

 object. This can be used to pass configuration into the 

 client instance, such as the API URL, custom fetch function, request policy and any additional middleware in the 

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 

 to create one after logging in with your GitHub account. We can then configure our 

 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_TOKEN = "<your token here>";

export default withUrqlClient(() => ({
  url: "https://api.github.com/graphql",
  fetchOptions: {
    headers: {
      authorization: `Bearer ${GITHUB_TOKEN}`,
    },
  },
}))(App);


 client set up, let us look at how we can use it to connect to the GitHub API and fetch some data.

We will build a simple component that will display a list of repositories, with each item showing a link to the repo, its name, star count and commit count. The component will look somewhat like this.

To start, let us look at the GraphQL query that should be used.

query Query {
  viewer {
    name
    repositories(first: 10, orderBy: { direction: DESC, field: STARGAZERS }) {
      nodes {
        name
        id
        url
        object(expression: "main") {
          ... on Commit {
            history {
              totalCount
            }
          }
        }
        stargazers {
          totalCount
        }
      }
    }
  }
}


This query fetches the first 10 repositories for the current user (determined from the personal access token). For each repository, it includes the name, ID, URL, stargazer count and the number of commits to the 

 branch. There are various other fields that can be added to the query, as documented in the 

. Since we're using TypeScript, let us model the API response with the correct expected types and use them as type parameters to 

type Repository = {
  name: string;
  id: string;
  url: string;
  object: {
    history: {
      totalCount: number;
    };
  };
  stargazers: {
    totalCount: number;
  };
};

type ListRepositoriesResponse = {
  viewer: {
    name: string;
    repositories: {
      nodes: Repository[];
    };
  };
};

const LIST_REPOSITORIES = `
  query ListRepositories {
    viewer {
      name
      repositories(first: 10, orderBy: { direction: DESC, field: STARGAZERS }) {
        nodes {
          name
          id
          url
          object(expression: "main") {
            ... on Commit {
              history {
                totalCount
              }
            }
          }
          stargazers {
            totalCount
          }
        }
      }
    }
  }`;

const [{ fetching, data }] = useQuery<ListRepositoriesResponse>({
    query: LIST_REPOSITORIES,
  });

 returns a number of useful items, out of which we will currently use the 

 flag which tells us whether or not the operation is still in progress, and the 

 property which contains the fetched data when available.

Let us now add some simple UI to render the returned data.

import { Inter } from "@next/font/google";
import styles from "../styles/Home.module.css";
import { useQuery } from "urql";

const inter = Inter({ subsets: ["latin"] });

type Repository = {
  name: string;
  id: string;
  url: string;
  object: {
    history: {
      totalCount: number;
    };
  };
  stargazers: {
    totalCount: number;
  };
};

type ListRepositoriesResponse = {
  viewer: {
    name: string;
    repositories: {
      nodes: Repository[];
    };
  };
};

const LIST_REPOSITORIES = `
  query ListRepositories {
    viewer {
      name
      repositories(first: 10, orderBy: { direction: DESC, field: STARGAZERS }) {
        nodes {
          name
          id
          url
          object(expression: "main") {
            ... on Commit {
              history {
                totalCount
              }
            }
          }
          stargazers {
            totalCount
          }
        }
      }
    }
  }`;

export default function Repositories() {
  const [{ fetching, data }] = useQuery<ListRepositoriesResponse>({
    query: LIST_REPOSITORIES,
  });

  return (
    <>
      {fetching && <h3 className={inter.className}>Loading...</h3>}
      {!!data && (
        <>
          <h3 className={inter.className}>
            Repositories for {data.viewer.name}
          </h3>
          <ul className={`${styles.repositories} ${inter.className}`}>
            {(data.viewer.repositories.nodes || []).map((repo: any) => (
              <li key={repo.id}>
                <a href={repo.url} target="_blank" rel="noopener noreferrer">
                  <h4 className={inter.className}>{repo.name}</h4>
                </a>
                <div className={styles.stats}>
                  <span className={inter.className}>
                    ⭐️ {repo.stargazers.totalCount}
                  </span>
                  <span className={inter.className}>
                    💾 {repo.object?.history?.totalCount ?? 0}
                  </span>
                </div>
              </li>
            ))}
          </ul>
        </>
      )}
    </>
  );
}


 component now fetches and renders a list of repositories with star and commit counts.

 in a Next.js app and use it to query the GitHub GraphQL API. Let's now take it a step further and learn how to create mutations - these are API operations that can cause the data to change in the backend.

For the purposes of this tutorial, we will implement the creation of an issue within a given GitHub repository.

The GraphQL mutation to create an issue looks like this:

mutation CreateIssue($repositoryId: ID!, $title: String!, $body: String!) {
  createIssue(input: {repositoryId: $repositoryId, title: $title, body: $body}) {
    issue {
      number
      body
      title
    }
  }
}

This mutation takes three variables - the repository ID to create the issue in, the title and the body of the issue. On success, it returns an 

 object that can contain the number, title and body.

So let us model the request variables and response, and create the mutation.

type CreateRepositoryVariables = {
  repositoryId: string;
  title: string;
  body: string;
};

type Issue = {
  number: number;
  body: string;
  title: string;
};

type CreateIssueResponse = {
  createIssue: {
    issue: Issue;
  };
};

const CREATE_ISSUE = `
  mutation CreateIssue($repositoryId: ID!, $title: String!, $body: String!) {
    createIssue(input: {repositoryId: $repositoryId, title: $title, body: $body}) {
      issue {
        number
        body
        title
      }
    }
  }
`;

const [{ fetching: creating, data: createResponse }, createIssue] =
      	useMutation<CreateIssueResponse, CreateRepositoryVariables>(CREATE_ISSUE);

 hook returns a tuple with two items - an object that exposes the current state of the mutation request, and a function that can be invoked with input variables to execute the actual mutation.

 component to be able to call this mutation. We'll refactor and extract some of the code into an individual 

 component will look like. All the GraphQL types have been moved to a separate 

import { Inter } from "@next/font/google";
import styles from "../styles/Home.module.css";
import { useQuery } from "urql";
import { ListRepositoriesResponse } from "./types";
import Repository from "./Repository";

const inter = Inter({ subsets: ["latin"] });

const LIST_REPOSITORIES = `
  query ListRepositories {
    viewer {
      name
      repositories(first: 10, orderBy: { direction: DESC, field: STARGAZERS }) {
        nodes {
          name
          id
          url
          object(expression: "main") {
            ... on Commit {
              history {
                totalCount
              }
            }
          }
          stargazers {
            totalCount
          }
        }
      }
    }
  }`;

export default function Repositories() {
  const [{ fetching, data }] = useQuery<ListRepositoriesResponse>({
    query: LIST_REPOSITORIES,
  });

  return (
    <>
      {fetching && <h3 className={inter.className}>Loading...</h3>}
      {!!data && (
        <>
          <h3 className={inter.className}>
            Repositories for {data.viewer.name}
          </h3>
          <ul className={`${styles.repositories} ${inter.className}`}>
            {(data.viewer.repositories.nodes || []).map((repo) => (
              <Repository repository={repo} key={repo.id} />
            ))}
          </ul>
        </>
      )}
    </>
  );
}


 component now renders the list item, along with a button that invokes the 

import { Inter } from "@next/font/google";
import styles from "../styles/Home.module.css";
import { useMutation } from "urql";
import {
  CreateIssueResponse,
  CreateRepositoryVariables,
  Repository,
} from "./types";

const inter = Inter({ subsets: ["latin"] });

const CREATE_ISSUE = `
  mutation CreateIssue($repositoryId: ID!, $title: String!, $body: String!) {
    createIssue(input: {repositoryId: $repositoryId, title: $title, body: $body}) {
      issue {
        number
        body
        title
      }
    }
  }
`;

type RepositoryProps = {
  repository: Repository;
};

export default function Repo({ repository }: RepositoryProps) {
  const [{ fetching, data: createResponse }, createIssue] = useMutation<
    CreateIssueResponse,
    CreateRepositoryVariables
  >(CREATE_ISSUE);

  return (
    <li key={repository.id}>
      <div className={styles.repositoryName}>
        <a href={repository.url} target="_blank" rel="noopener noreferrer">
          <h4 className={inter.className}>{repository.name}</h4>
        </a>
        <button
          className={styles.createIssue}
          onClick={async () => {
            await createIssue({
              repositoryId: repository.id,
              title: "This is a test issue",
              body: "Test issue body",
            });
          }}
        >
          + Create Issue
        </button>
      </div>
      <div className={styles.stats}>
        <span className={inter.className}>
          ⭐️ {repository.stargazers.totalCount}
        </span>
        <span className={inter.className}>
          💾 {repository.object?.history?.totalCount ?? 0}
        </span>
      </div>
    </li>
  );
}


Clicking the button creates an issue with a sample fixed title and body in the corresponding repo.

💡 This was a simplified example only intended to show the use of the 

 hook. You can expand upon it and add more features like the ability to customize the title and body, a loading indicator, more visual feedback and error handling.

 is modeled as an 'operation', and the system at any moment has a stream of operations issued by various parts of the app. 

 are pieces of middleware that transform the stream of operations into a stream of results. This is explained in more detail in the 

's core features such as fetching data and caching are also handled via exchanges implemented by the 

 team and provided by default. You can also create your own exchanges by implementing functions that conform to the rules defined 

Server-Side Rendered apps need to be set up to fetch data on the server-side and send it down to the client for hydration. 

The SSR exchange has two functions - it gathers all the data as it is being fetched server-side, and using the serialized data on the client side to rehydrate the app without a refetch.

, most of the boilerplate involved in instantiating the 

 is already done for you. So if your client does not use any other exchanges, you do not explicitly need to instantiate the 

 when creating the client. To enable SSR, you simply need to set the 

 flag in the second argument to the client configuration function.

const token = "<your token here>";

export default withUrqlClient(() => ({
  url: "https://api.github.com/graphql",
  fetchOptions: {
    headers: {
      authorization: "Bearer " + token,
    },
  },
}), { ssr: true })(App);

If you do want to add other exchanges to your client, they can be specified in an 

 property returned by the configuration function. This function also gets the instance of the 

import { dedupExchange, cacheExchange, fetchExchange } from '@urql/core';

const token = "<your token here>";

export default withUrqlClient((ssrExchange) => ({
  url: "https://api.github.com/graphql",
  exchanges: [dedupExchange, cacheExchange, ssrExchange, fetchExchange],
  fetchOptions: {
    headers: {
      authorization: "Bearer " + token,
    },
  },
}), { ssr: true })(App);

Enabling SSR when wrapping the top level 

' which allows for hybrid apps with both server-side rendered and statically generated pages. If this is required in your app, you can wrap individual page components with 

 cache. This will render the page as a static page, further optimizing performance and allowing us to perform other operations in these functions.

Let us adapt our app to use server-side rendering with 

 to our Home page component, as this function can only be exported from page components.

import Head from "next/head";
import { withUrqlClient, initUrqlClient, NextUrqlPageContext } from "next-urql";
import { ssrExchange, dedupExchange, cacheExchange, fetchExchange } from "urql";
import styles from "../styles/Home.module.css";
import { Repositories } from "../components";
import { LIST_REPOSITORIES } from "./queries";

function Home() {
  return (
    <>
      <Head>
        <title>Next.js + URQL Example App</title>
        <meta name="description" content="Next.js + URQL Example App" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <main className={styles.main}>
        <Repositories />
      </main>
    </>
  );
}

const token = "<your token here>";

export async function getServerSideProps(ctx: NextUrqlPageContext) {
  const ssrCache = ssrExchange({ isClient: false });
  const client = initUrqlClient(
    {
      url: "https://api.github.com/graphql",
      fetchOptions: {
        headers: {
          authorization: "Bearer " + token,
        },
      },
      exchanges: [dedupExchange, cacheExchange, ssrCache, fetchExchange],
    },
    false
  );

  if (!client) {
    return;
  }

  await client.query(LIST_REPOSITORIES, {}).toPromise();

  return {
    props: {
      urqlState: ssrCache.extractData(),
    },
  };
}

export default withUrqlClient(() => ({
  url: "https://api.github.com/graphql",
  fetchOptions: {
    headers: {
      authorization: "Bearer " + token,
    },
  },
}))(Home);


 function gets called when the page is being rendered server-side. It will populate the cache so that the subsequent render of the 

 component will hydrate it from cache when 

In this article, we have learnt how to set up 

 with a Next.js app and perform queries and mutations against the GitHub GraphQL API.

Further, we have also learnt about the architecture of 

 to implement server side rendering with pre-fetching of queries using the 

In a subsequent tutorial, we will learn how to use 

 exchanges for authentication and caching.

All the code used in this article is available on my 

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

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

Responses (1)

Masterclasses

Tutorials

Fullstack React with TypeScript