next-urqlA set of convenience utilities for using urql with NextJS.
Using GraphQL with server-side rendering in React is a challenging problem. Currently, React has no support for Suspense for data fetching on the server. To get around this, a prepass step can be used to walk the tree (or a subsection of the tree) of your React application and suspend when it encounters thrown Promises. For more information, check out react-ssr-prepass.
next-urql handles integrating this prepass step for you, such that your NextJS application using urql will prefetch your GraphQL queries on the server before sending down markup to the client.
Install next-urql along with its peerDependencies.
npm install --save next-urql react-is styled-components isomorphic-unfetch
react-is, styled-components, and isomorphic-unfetch help to support server-side Suspense with react-ssr-prepass. This assumes you have followed the basic installation steps for urql here.
To use next-urql, first import the withUrqlClient higher order component.
import { withUrqlClient } from 'next-urql';
Then, for any page in your pages directory for which you want to prefetch GraphQL queries, wrap the page in withUrqlClient. For example, let's say you have an index.js page that renders two components that make GraphQL requests using urql, PokemonList and PokemonTypes. To run their queries initially on the server-side you'd do something like the following:
import React from 'react';
import Head from 'next/head';
import { withUrqlClient } from 'next-urql';
import PokemonList from '../components/pokemon_list';
import PokemonTypes from '../components/pokemon_types';
const Root = () => (
<div>
<Head>
<title>Root</title>
<link rel="icon" href="/static/favicon.ico" />
</Head>
<PokemonList />
<PokemonTypes />
</div>
);
export default withUrqlClient({ url: 'https://graphql-pokemon.now.sh' })(Root);
Read more below in the API section to learn more about the arguments that can be passed to withUrqlClient.
_app.jsNext allows you to override the root of your application using a special page called _app.js. If you want to have all GraphQL requests in your application fetched on the server-side, you could wrap the component exported by _app.js in withUrqlClient. However, be aware that this will opt you out of automatic static optimization for your entire application. In general, it's recommended practice to only use withUrqlClient on the pages that have GraphQL operations in their component tree. Read more in the Caveats section.
next-urql exposes a single higher order component, withUrqlClient. This HoC accepts two arguments:
clientOptions (Required)The clientOptions argument is required. It represents all of the options you want to enable on your urql Client instance. It has the following type:
export interface ClientOptions {
/** The GraphQL endpoint your application is using. */
url: string;
/** Any additional options to pass to fetch. */
fetchOptions?: RequestInit | (() => RequestInit);
/** An alternative fetch implementation. */
fetch?: typeof fetch;
/** The default request policy for requests. */
requestPolicy?: RequestPolicy;
}
In client-side SPAs using urql, you typically configure the Client yourself and pass it as the value prop to urql's context Provider. withUrqlClient handles setting all of this up for you under the hood. By default, you'll be opted into server-side Suspense and have the necessary exchanges setup for you, including the ssrExchange. If you need to customize your exchanges beyond the defaults next-urql provides, use the second argument to withUrqlClient, mergeExchanges.
mergeExchanges (Optional)The mergeExchanges argument is optional. This is a function that takes the ssrExchange created by next-urql as its only argument and allows you to configure your exchanges as you wish. It has the following type signature:
(ssrExchange: SSRExchange) => Exchange[]
By default, next-urql will incorprate the ssrExchange into your exchanges array in the correct location (after any other caching exchanges, but before the fetchExchange – read more here). Use this argument if you want to configure your client with additional custom exchanges, or access the ssrCache directly to extract or restore data from its cache.
You can see an example project with next-urql in our example directory or on CodeSandbox.
withUrqlClient implements NextJS's unique getInitialProps method uner the hood. This means that any page containing a component wrapped by withUrqlClient will be opted out of automatic static optimization. Automatic static optimization was added in Next v9, so you shouldn't worry about this if using an earlier version of Next. This is not unique to next-urql – any implementation of getInitialProps by any component in your application will cause Next to opt out of automatic static optimization.
FAQs
Convenience wrappers for using urql with NextJS.
The npm package next-urql receives a total of 11,120 weekly downloads. As such, next-urql popularity was classified as popular.
We found that next-urql demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 25 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.