In this article, we will learn how to use the urql 

 to add authentication with a GraphQL API in a Next.js app.

 to execute queries and mutations in a Next.js Server-Side Rendered app.

In the following sections, we will recap those learnings and build on them to implement authentication using 

 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 

 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 

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 

Installing next-urql and @urql/exchange-auth

npm install --save next-urql react-is @urql/exchange-auth jwt-decode

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

 that we will implement our API authentication with. Finally, 

 will be used to read the token and determine expiration time.

 to quickly scaffold out a login/register component and one that renders user info. Let us install the required dependencies for Material UI.

npm install @mui/material @emotion/react @emotion/styled

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

 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 

import "../styles/globals.css";
import type { AppProps } from "next/app";
import { withUrqlClient } from "next-urql";

function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

const GITHU

TOKEN = "<your token here>";

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

In this tutorial, we will build a simple app with two screens - a login/register screen where users will authenticate or sign up to the app, and a user info screen that displays information about the logged in user.

We will use the following operations from the Web Collections Demo API:

We will use the browser's local storage to persist tokens across page reloads.

 client, which intends to facilitate the typical 

 based authentication flow with a simple and flexible API. It is provided in the 

 itself takes four pieces of configuration:

Implementing JWT Authentication with urql's 

Persisting and Retrieving Tokens from Local Storage

 mutations from our API return an object that has the following shape.

export type AuthState = {
  token: string;
  refreshToken: string;
};

Let us implement a small helper function that stores the auth state in the browser's local storage.

const TOKEN_KEY = "token";
const REFRESH_TOKEN_KEY = "refresh_token";

export const saveAuthState = ({ token, refreshToken }: AuthState) => {
  if (typeof window === "undefined") return;
  localStorage.setItem(TOKEN_KEY, token);
  localStorage.setItem(REFRESH_TOKEN_KEY, refreshToken);
};

 since we only want this code to run in the browser.

When the user logs out, we'd like to clear the auth state from storage.

export const clearAuthState = () => {
  if (typeof window === "undefined") return;
  localStorage.removeItem(TOKEN_KEY);
  localStorage.removeItem(REFRESH_TOKEN_KEY);
};

We can now add a couple of convenience functions to fetch the token and refresh token.

export const getToken = () => {
  if (typeof window === "undefined") return;
  return localStorage.getItem(TOKEN_KEY);
};

export const getRefreshToken = () => {
  if (typeof window === "undefined") return;
  return localStorage.getItem(REFRESH_TOKEN_KEY);
};

 - this function needs to handle a couple of different scenarios:

Attaching the Token to the Request Headers using 

 function receives two parameters - the first is the current 

, and the second is the operation that will be executed next.

 and is urql's way of representing an item in the stream of GraphQL requests. Operations have a context that contains the fetch options, either as an object or as an initializer function. We will retrieve the options for the current operation like so.

const fetchOptions =
    typeof operation.context.fetchOptions === "function"
		? operation.context.fetchOptions()
		: operation.context.fetchOptions || {};

We'll then create a new operation which is basically a clone of the input operation, along with our required override - the addition of our access token to the 

return makeOperation(operation.kind, operation, {
  ...operation.context,
  fetchOptions: {
    ...fetchOptions,
    headers: {
      ...fetchOptions.headers,
      Authorization: `Bearer ${authState.token}`,
    },
  },
});

type AddAuthToOperationInput = {
  authState: AuthState;
  operation: Operation<any, any>;
};

function addAuthToOperation({ authState, operation }: AddAuthToOperationInput) {
  if (!authState || !authState.token) {
    return operation;
  }

  const fetchOptions =
    typeof operation.context.fetchOptions === "function"
      ? operation.context.fetchOptions()
      : operation.context.fetchOptions || {};

  return makeOperation(operation.kind, operation, {
    ...operation.context,
    fetchOptions: {
      ...fetchOptions,
      headers: {
        ...fetchOptions.headers,
        Authorization: `Bearer ${authState.token}`,
      },
    },
  });
}

Our API uses the GraphQL error code extension to communicate errors. For the purposes of this tutorial, we will only consider 

type DidAuthErrorInput = {
  error: CombinedError;
  authState: AuthState | null;
};

function didAuthError({ error }: DidAuthErrorInput) {
  return error.graphQLErrors.some((e) => e.extensions?.code === "UNAUTHORIZED");
}

Token expiry is one of the scenarios when we know the API will error. We are able to determine this by decoding the JWT and reading the 

 field which specifies the expiration time. 

Our API's access token specifies the expiration time as seconds since the Unix epoch. Let us add a buffer of 5 seconds to determine that the token is about to expire.

const decoded = jwtDecode<{ exp: number }>(getToken() as string);
const isExpiring = decoded.exp * 1000 - new Date().getTime() <= 5000;

return isExpiring;

Now, this would work if all of our queries and mutations required the access token to be provided. However, we have mutations such as 

 which do not require the token passed in. We will need to adapt our logic to account for these mutations, and this can be done using the passed in 

type WillAuthErrorInput = {
  operation: Operation<any, any>;
  authState: AuthState | null;
};

function willAuthError({ operation, authState }: WillAuthErrorInput) {
  if (!authState) {
    return !(
      operation.kind === "mutation" &&
      operation.query.definitions.some((definition) => {
        return (
          definition.kind === "OperationDefinition" &&
          definition.selectionSet.selections.some((node) => {
            return (
              node.kind === "Field" &&
              (node.name.value === "login" || node.name.value === "register")
            );
          })
        );
      })
    );
  } else {
    const decoded = jwtDecode<{ exp: number }>(getToken() as string);
    const isExpiring = decoded.exp * 1000 - new Date().getTime() <= 5000;
    return operation.kind === "query" && isExpiring;
  }
}

Now that we have implemented all the required functions, the final step is to configure the 

Let us create a factory function that receives the 

 and returns a client configuration object.

export const clientOptions = (ssrExchange: SSRExchange) => ({
  url: "https://trygql.formidable.dev/graphql/web-collections",
  exchanges: [
    dedupExchange,
    cacheExchange,
    ssrExchange,
    authExchange<AuthState>({
      getAuth,
      addAuthToOperation,
      didAuthError,
      willAuthError,
    }),
    fetchExchange,
  ],
});

We'll use this on our app's homepage in the next section.

Our home page will render the login form when unauthenticated, and a user profile when the user is logged in. We'll use our 

import React from "react";
import Head from "next/head";
import { withUrqlClient } from "next-urql";
import styles from "../styles/Home.module.css";
import { clientOptions } from "../shared/client";
import Login from "./Login";
import { AuthState, getToken, saveAuthState } from "../shared/auth";
import Profile from "./Profile";

function Home() {
  const [isLoggedIn, setIsLoggedIn] = React.useState(false);

  const onLoginSuccess = (auth: AuthState) => {
    saveAuthState(auth);
    setIsLoggedIn(true);
  };

  React.useEffect(() => {
    if (getToken()) {
      setIsLoggedIn(true);
    }
  }, []);
  return (
    <>
      <Head>
        <title>Next.js + URQL JWT Authentication</title>
        <meta name="description" content="Next.js + URQL JWT Authentication" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <main className={styles.main}>
        {isLoggedIn ? <Profile /> : <Login onLogin={onLoginSuccess} />}
      </main>
    </>
  );
}

export default withUrqlClient((ssrExchange) => clientOptions(ssrExchange))(
  Home
);


const LOGIN_MUTATION = gql`
  mutation Login($input: LoginInput!) {
    signin(input: $input) {
      refreshToken
      token
    }
  }
`;

const REGISTER_MUTATION = gql`
  mutation Register($input: LoginInput!) {
    register(input: $input) {
      refreshToken
      token
    }
  }
`;

 hook can be used to consume these mutations within a React component.

type Credentials = {
  token: string;
  refreshToken: string;
};

type SignInResponse = {
  signin: Credentials;
};

type RegisterResponse = {
  register: Credentials;
};

const [{ fetching: isLoggingIn, error: loginError }, login] =
    useMutation<SignInResponse>(LOGIN_MUTATION);
const [{ fetching: isRegistering, error: registerError }, register] =
    useMutation<RegisterResponse>(REGISTER_MUTATION);

 hook returns a tuple containing the current state of the operation, and a function that triggers it. We'll trigger our mutations on submission of the respective form.

Here is the full implementation of the page.

import { LoadingButton } from "@mui/lab";
import {
  Tabs,
  Tab,
  Typography,
  FormControl,
  Input,
  InputLabel,
  Stack,
  Box,
  CircularProgress,
  Button,
  Alert,
} from "@mui/material";
import React from "react";
import { gql, useMutation } from "urql";

const LOGIN_MUTATION = gql`
  mutation Login($input: LoginInput!) {
    signin(input: $input) {
      refreshToken
      token
    }
  }
`;

const REGISTER_MUTATION = gql`
  mutation Register($input: LoginInput!) {
    register(input: $input) {
      refreshToken
      token
    }
  }
`;

type Credentials = {
  token: string;
  refreshToken: string;
};

type SignInResponse = {
  signin: Credentials;
};

type RegisterResponse = {
  register: Credentials;
};

type LoginProps = {
  onLogin: (creds: Credentials) => any;
};

const Login = ({ onLogin }: LoginProps) => {
  const [tab, setTab] = React.useState("login");
  const [{ fetching: isLoggingIn, error: loginError }, login] =
    useMutation<SignInResponse>(LOGIN_MUTATION);
  const [{ fetching: isRegistering, error: registerError }, register] =
    useMutation<RegisterResponse>(REGISTER_MUTATION);

  const onSubmitLogin = (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    const data = new FormData(event.target as HTMLFormElement);
    const username = data.get("username");
    const password = data.get("password");

    login({ input: { username, password } }).then((result) => {
      if (!result.error && result.data && result.data.signin) {
        onLogin(result.data.signin);
      }
    });
  };

  const onSubmitRegister = (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    const data = new FormData(event.target as HTMLFormElement);
    const username = data.get("username");
    const password = data.get("password");

    register({ input: { username, password } }).then((result) => {
      if (!result.error && result.data && result.data.register) {
        onLogin(result.data.register);
      }
    });
  };

  return (
    <Stack
      sx={{
        width: "100vw",
        height: "100vh",
        justifyContent: "center",
        alignItems: "center",
      }}
    >
      <Box
        sx={{
          border: (theme) => `1px solid ${theme.palette.grey[300]}`,
          borderRadius: 1,
          p: 2,
          minWidth: 400,
        }}
      >
        <Tabs value={tab} onChange={(e, value) => setTab(value)}>
          <Tab label="Log In" value="login" />
          <Tab label="Register" value="register" />
        </Tabs>
        {tab === "login" && (
          <form onSubmit={onSubmitLogin}>
            <Stack p={2} gap={2}>
              {loginError && (
                <Alert severity="error">{loginError.message}</Alert>
              )}
              <Typography variant="h5">Log in</Typography>
              <FormControl variant="standard">
                <InputLabel htmlFor="username">Username</InputLabel>
                <Input id="username" name="username" defaultValue="" />
              </FormControl>
              <FormControl variant="standard">
                <InputLabel htmlFor="password">Password</InputLabel>
                <Input
                  id="password"
                  name="password"
                  type="password"
                  defaultValue=""
                />
              </FormControl>
              <Button
                startIcon={
                  isLoggingIn ? <CircularProgress size={16} /> : undefined
                }
                disabled={isLoggingIn}
                type="submit"
              >
                Log In
              </Button>
            </Stack>
          </form>
        )}

        {tab === "register" && (
          <form onSubmit={onSubmitRegister}>
            <Stack p={2} gap={2}>
              {registerError && (
                <Alert severity="error">{registerError.message}</Alert>
              )}
              <Typography variant="h5">Register</Typography>
              <FormControl variant="standard">
                <InputLabel htmlFor="username">Username</InputLabel>
                <Input id="username" name="username" defaultValue="" />
              </FormControl>
              <FormControl variant="standard">
                <InputLabel htmlFor="password">Password</InputLabel>
                <Input
                  id="password"
                  name="password"
                  type="password"
                  defaultValue=""
                />
              </FormControl>
              <LoadingButton
                loadingIndicator="Registering..."
                loading={isRegistering}
                disabled={isRegistering}
                type="submit"
              >
                Register
              </LoadingButton>
            </Stack>
          </form>
        )}
      </Box>
    </Stack>
  );
};

export default Login;


 query from the API to retrieve the user's ID, name and creation time.

const PROFILE_QUERY = gql`
  query Profile {
    me {
      id
      username
      createdAt
    }
  }
`;

const [{ data, fetching, error }] = useQuery({ query: PROFILE_QUERY });

 components to display the profile data. This will also include a loading indicator and an alert to show any error messages.

<Stack justifyContent="center" alignItems="center">
  {fetching && <CircularProgress />}
  {!!error && <Alert severity="error">{error.message}</Alert>}
  {!!data && (
    <Stack>
      <Typography variant="caption">User ID</Typography>
      <Typography variant="h5">{data?.me?.id ?? ""}</Typography>
      <Typography variant="caption">Username</Typography>
      <Typography variant="h5">{data?.me?.username ?? ""}</Typography>
      <Typography variant="caption">Created</Typography>
      <Typography variant="h5">
        {new Date(data?.me?.createdAt ?? "").toDateString()}
      </Typography>
    </Stack>
  )}
</Stack>

In this article, we have learnt how to implement JWT authentication with a GraphQL API using 

 with a Next.js app. We have understood how to apply authentication to queries and mutations, and built a simple app that allows login and registration.

All the code used in this article is available on my 

AUTHOR

Krishna Acondy

In this article, we will learn how to use the urql authExchange to add authentication with a GraphQL API in a Next.js app.

Learn

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

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

How to use urql authExchange to implement authentication in Next.js

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript