persisted-fetch-exchange.md

title	order
@urql/exchange-persisted-fetch	8

Persisted Fetch Exchange

The @urql/exchange-persisted-fetch package contains an addon persistedFetchExchange for urql that enables the use of Automatic Persisted Queries with urql.

It follows the unofficial GraphQL Persisted Queries Spec which is supported by the Apollo Sever package.

This exchange uses the same fetch logic as the fetchExchange and the multipartFetchExchange by reusing logic from @urql/core/internal. The persistedFetchExchange will attempt to send queries with an additional SHA256 hash to the GraphQL API and will otherwise, when Automatic Persisted Queries are unsupported or when a mutation or subscription is sent, forward the operation to the next exchange. Hence it should always be added in front of another fetchExchange.

The persistedFetchExchange will use the built-in Web Crypto API for SHA256 hashing in the browser, which has been implemented to support IE11 as well. In Node.js it'll use the Node Crypto Module instead. It's also possible to use the generateHash option to alter how the SHA256 hash is generated or retrieved.

Installation and Setup

First install @urql/exchange-persisted-fetch alongside urql:

yarn add @urql/exchange-persisted-fetch
# or
npm install --save @urql/exchange-persisted-fetch

You'll then need to add the persistedFetchExchange, that this package exposes, to your exchanges, in front of the fetchExchange. If you're using the multipartFetchExchange then it must be added in front of that instead:

import { createClient, dedupExchange, fetchExchange, cacheExchange } from 'urql';
import { persistedFetchExchange } from '@urql/exchange-persisted-fetch';

const client = createClient({
  url: 'http://localhost:1234/graphql',
  exchanges: [
    dedupExchange,
    cacheExchange,
    persistedFetchExchange({
      /* optional config */
    }),
    fetchExchange,
  ],
});

Options

Option	Description
preferGetForPersistedQueries	This is similar to the Client's preferGetMethod option and will cause all persisted queries to be sent using a GET request.
enforcePersistedQueries	This option enforced persisted queries. Instead of allowing automatic persisted queries or triggering any retry logic when the API responds, it instead assumes that persisted queries will succeed and run like normal GraphQL API requests.
generateHash	This option accepts a function that receives the query as a string and the raw DocumentNode as a second argument and must return a Promise<string> resolving to a SHA256 hash. This can be used to swap out the SHA256 API, e.g. for React Native, or to use pre-generated SHA256 strings from the DocumentNode.