Tutorial: How to Setup URQL in a Next.js Typescript App

Jasser Mark Arioste

Jasser Mark Arioste

Tutorial: How to Setup URQL in a Next.js Typescript App

I'm going to show you how to set up URQL in a brand-new NextJS project. This post will cover installation, code generation in typescript, and using the hooks for GraphQL queries. We'll be using Rick and Morty GraphQL API as our backend endpoint for simplicity, and query the list of episodes and display them on the UI. 

Installation  #

Create a next.js project using npx with typescript option. 

npx create-next-app --ts urql-nextjs-starter

Install the dependencies

#Install graphql and urql
yarn add graphql@15.x urql

#Install tools for code type generation in typescript
yarn add -D @graphql-codegen/cli @graphql-codegen/near-operation-file-preset @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-urql @graphql-codegen/urql-introspection

Creating the config file #

Create a graphql.config.yml in the root directory of your project folder and copy the code below. Please check the comments if you want to know what each line means. 

overwrite: true
schema: ""
documents: "graphql/**/*.graphql" # documents - where our graphql queries will reside
  graphql/types.tsx: #generate/types.tsx for typesafety during development
      - "typescript"
    #useful so that it doesn't generate 1 big file but separate them per .graphql file
    preset: near-operation-file
      extension: .gql.tsx
      baseTypesPath: types.ts
    # generates react hooks for urql
      - "typescript-operations"
      - "typescript-urql"
      withHooks: true

Add a new command in our package.json file for code generation. This command will generate the types and react hooks to make development easier and solid.

  "scripts": {
    "gen": "graphql-codegen --config graphql.config.yml"

Let's create the GraphQL Query #

Let's create the graphql folder and episodes.graphql

mkdir graphql && cd graphql
touch episodes.graphql

Let's paste our query inside episodes.graphql

query Episodes($page: Int) {
  episodes(page: $page) {
    results {

Generate the code #

yarn gen 
npm run gen

You should be able to see the generated files inside /graphql folder. Below would be how our directory will look like after all these steps. This is important in when developing in typescript since it basically ensures that there are no incorrectly called queries in our frontend with all the types and hooks generated for us. Now we are ready to query rick and morty api and show it in our UI!

Folder structure with generated types

And we now have both  auto-complete for the variables and the returned data (type safety). Awesome!

Auto complete for variables
Autocomplete for the results

Using the generated react hooks to fetch some data! #

Let's add the hook in our index.tsx file and render the list. I added a little bit of styling too.

import type { NextPage } from "next";
import { useEpisodesQuery } from "../graphql/episodes.gql";

const Home: NextPage = () => {
  const [{ data }] = useEpisodesQuery({
    variables: {
      page: 1,

  const episodes = data?.episodes?.results;
  return (
    <div className="container">
      <ol className="episode-list">
        {episodes?.map((episode, i) => {
          return (
            <li key={i} className="episode">
              <h2 className="episode-title">{episode?.name}</h2>
              <p className="episode-ep">{episode?.episode}</p>
              <time dateTime={episode?.air_date ?? ""}>

export default Home;

What about Server-side Rendering (SSR)? #

For Server-side Rendering (SSR), I created a separate tutorial on how to set up URQL SSR with NextJS.

Conclusion #

We've learned on how to setup URQL with Next.js along with code generation to make sure that all our types and queries are called correctly
Full code is available here:
Demo is available here: 

Share this post!

Related Posts


This content may contain links to products, software and services. Please assume all such links are affiliate links which may result in my earning commissions and fees.
As an Amazon Associate, I earn from qualifying purchases. This means that whenever you buy a product on Amazon from a link on our site, we receive a small percentage of its price at no extra cost to you. This helps us continue to provide valuable content and reviews to you. Thank you for your support!
Donate to ReactHustle