graphql-react

graphql-react

A lightweight but powerful GraphQL client for React using modern context and hooks APIs; the first Relay and Apollo alternative with server side rendering.

• Apollo comparison
• Setup
• Usage
• Examples
• Support
• API

Apollo comparison

Bundle impact

graphql-react

A < 2.5 KB bundle impact is guaranteed by size-limit tests. The impact is smaller than the bundle size badge suggests as the internal object-assign dependency is shared with react.

Dependency	Install size	Bundle size
graphql-react

Tree shaking bundlers will eliminate unused exports (perhaps reportCacheErrors).

Apollo

Several dependencies must be installed for a minimal Apollo project.

Dependency	Install size	Bundle size
apollo-boost
react-apollo
graphql-tag
graphql

Tree shaking bundlers will eliminate unused graphql exports.

In addition, fragment matcher config impacts bundle size relative to the number and complexity of schema unions and interfaces; see Cache strategy.

Native ESM

graphql-react

Supports native ESM via .mjs files for Node.js in --experimental-modules mode and tree shaking bundlers like webpack. For legacy environments CJS is provided via .js files.

Apollo

No support for native ESM, although they do provide faux ESM via package module fields for tree shaking bundlers like webpack.

Writing queries

graphql-react

Uses template strings:

const QUERY = /* GraphQL */ `
  {
    viewer {
      id
    }
  }
`

The optional /* GraphQL */ comment signals the syntax for highlighters and linters.

Apollo

Uses template strings tagged with gql from graphql-tag:

import gql from 'graphql-tag'

const QUERY = gql`
  {
    viewer {
      id
    }
  }
`

Cache strategy

graphql-react

The GraphQL client has no GraphQL API specific config; fetch options are determined on demand at the component level. Multiple GraphQL APIs can be queried!

GraphQL operations are cached under hashes of their fetch options. Multiple operations with the same hash share the same loading status and cache value.

fetch, HTTP, parse and GraphQL errors can be cached, and therefore server side rendered and transported to the client for hydration and initial render.

Apollo

Apollo Client is configured for one GraphQL API per app.

GraphQL operation data is deconstructed based upon id and __typename fields into a “normalized” cache. These fields must be queried even if they aren’t used in components.

Errors aren’t cached, and therefore can’t be server side rendered and transported to the client for hydration and initial render.

Apollo Client must be configured with schema knowledge extracted at build time for a “fragment matcher” to cache fragments on unions and interfaces properly. It’s challenging to reconfigure and redeploy clients whenever the GraphQL schema updates. Also, the config increases the client bundle size; see Bundle impact.

Stale cache

graphql-react

By default, cache is refreshed for mounting components.

GraphQL operations can optionally refresh all cache except their own fresh cache; handy for mutations.

Apollo

By default, cache isn’t refreshed for mounting components.

GraphQL mutations only update the cache with the contents of their payload. The prescribed approach is to try to manually update other normalized cache after mutations using complicated and often buggy APIs. Resetting all cache is possible, but it also wipes the result of the last operation.

File uploads

graphql-react

Out of the box file uploads compliant with the GraphQL multipart request spec (authored by @jaydenseric) which is supported by popular GraphQL servers including Apollo Server. File input values can be used as query or mutation arguments.

Apollo

Supports file uploads if you drop apollo-boost and manually setup Apollo Client with apollo-upload-client (also by @jaydenseric).

Subscriptions

graphql-react

Not supported yet.

Apollo

Supported.

TypeScript

graphql-react

Written in ECMAScript; no types are exported.

Apollo

Written in TypeScript; types are exported.

Next.js integration

graphql-react

Has an official example using next-graphql-react, which provides easy an easy to install App decorator and plugin to enable server side rendered GraphQL queries.

Apollo

Has an official example, but it consists of over 100 lines of complicated copy-paste boilerplate code across multiple files.

Setup

Next.js setup

See the next-graphql-react setup instructions.

Vanilla React setup

To install graphql-react from npm run:

npm install graphql-react

Create a single GraphQL instance and use GraphQLContext to provide it for your app.

For server side rendering see ssr().

Usage

Use the useGraphQL React hook in your components to make queries and mutations, or use the GraphQL instance method operate directly.

Examples

• The official Next.js example.
• The Next.js example deployed at graphql-react.now.sh.

Support

• Node.js v8.5+
• Browsers > 0.5%, not dead

Consider polyfilling:

• Promise
• fetch
• FormData

API

Table of contents

• class GraphQL
  • See
  • Examples
  • GraphQL instance method off
  • GraphQL instance method on
    • See
  • GraphQL instance method operate
  • GraphQL instance method reload
    • Examples
  • GraphQL instance method reset
    • Examples
  • GraphQL instance property cache
    • Examples
  • GraphQL instance property operations
• function reportCacheErrors
  • Examples
• function ssr
  • See
  • Examples
• function useGraphQL
  • See
  • Examples
• constant GraphQLContext
  • See
  • Examples
• type GraphQLCache
  • See
• type GraphQLCacheKey
• type GraphQLCacheValue
• type GraphQLFetchOptions
  • See
• type GraphQLFetchOptionsOverride
  • See
  • Examples
• type GraphQLOperation
  • See
• type GraphQLOperationLoading
  • See
• type GraphQLOperationStatus
  • See
• type HttpError
• type ReactNode

class GraphQL

A lightweight GraphQL client that caches queries and mutations.

Parameter	Type	Description
options	Object? = {}	Options.
options.cache	GraphQLCache? = {}	Cache to import; usually from a server side render.

See

• reportCacheErrors to setup error reporting.

Examples

Construct a GraphQL client.

import { GraphQL } from 'graphql-react'

const graphql = new GraphQL()

GraphQL instance method off

Removes an event listener.

Parameter	Type	Description
type	String	Event type.
handler	function	Event handler.

GraphQL instance method on

Adds an event listener.

Parameter	Type	Description
type	String	Event type.
handler	function	Event handler.

See

• reportCacheErrors can be used with this to setup error reporting.

GraphQL instance method operate

Loads or reuses an already loading GraphQL operation in GraphQL operations. Emits a GraphQL instance fetch event if an already loading operation isn’t reused, and a cache event once it’s loaded into the GraphQL cache.

Parameter	Type	Description
options	Object	Options.
options.operation	GraphQLOperation	GraphQL operation.
options.fetchOptionsOverride	GraphQLFetchOptionsOverride?	Overrides default GraphQL operation fetch options.
options.reloadOnLoad	boolean? = false	Should a GraphQL reload happen after the operation loads, excluding the loaded operation cache.
options.resetOnLoad	boolean? = false	Should a GraphQL reset happen after the operation loads, excluding the loaded operation cache.

Returns: GraphQLOperationLoading — Loading GraphQL operation details.

GraphQL instance method reload

Signals that GraphQL cache subscribers such as the useGraphQL React hook should reload their GraphQL operation. Emits a GraphQL instance reload event.

Parameter	Type	Description
exceptCacheKey	GraphQLCacheKey?	A GraphQL cache key for cache to exempt from reloading.

Examples

Reloading the GraphQL cache.

graphql.reload()

GraphQL instance method reset

Resets the GraphQL cache, useful when a user logs out. Emits a GraphQL instance reset event.

Parameter	Type	Description
exceptCacheKey	GraphQLCacheKey?	A GraphQL cache key for cache to exempt from deletion. Useful for resetting cache after a mutation, preserving the mutation cache.

Examples

Resetting the GraphQL cache.

graphql.reset()

GraphQL instance property cache

Cache of loaded GraphQL operations. You probably don’t need to interact with this unless you’re implementing a server side rendering framework.

Type: GraphQLCache

Examples

Export cache as JSON.

const exportedCache = JSON.stringify(graphql.cache)

Example cache JSON.

{
  "a1bCd2": {
    "data": {
      "viewer": {
        "name": "Jayden Seric"
      }
    }
  }
}

GraphQL instance property operations

A map of loading GraphQL operations. You probably don’t need to interact with this unless you’re implementing a server side rendering framework.

Type: Object<GraphQLCacheKey, Promise<GraphQLCacheValue>>

---

function reportCacheErrors

A GraphQL cache event handler that reports fetch, HTTP, parse and GraphQL errors via console.log(). In a browser environment the grouped error details are expandable.

Parameter	Type	Description
data	Object	GraphQL cache event data.
data.cacheKey	GraphQLCacheKey	GraphQL cache key.
data.cacheValue	GraphQLCacheKey	GraphQL cache value.

Examples

GraphQL initialized to report cache errors.

import { GraphQL, reportCacheErrors } from 'graphql-react'

const graphql = new GraphQL()
graphql.on('cache', reportCacheErrors)

---

function ssr

Asynchronously server side renders a React node, preloading all GraphQL queries set to loadOnMount. After resolving, cache can be exported from the GraphQL instance property cache for serialization (usually to JSON) and transport to the client for hydration via the GraphQL constructor parameter options.cache.

Be sure to globally polyfill fetch.

Parameter	Type	Description
graphql	GraphQL	GraphQL instance.
node	ReactNode	React virtual DOM node.
render	function? = ReactDOMServer.renderToStaticMarkup	Synchronous React server side render function, defaulting to ReactDOMServer.renderToStaticMarkup as it is more efficient than ReactDOMServer.renderToString.

Returns: Promise<string> — Promise resolving the rendered HTML string.

See

• ReactDOMServer docs.
• next-graphql-react to use this API in a Next.js project.

Examples

SSR function that resolves a HTML string and cache JSON for client hydration.

import { GraphQL, GraphQLContext } from 'graphql-react'
import { ssr } from 'graphql-react/server'
import ReactDOMServer from 'react-dom/server'
import { App } from './components'

async function render() {
  const graphql = new GraphQL()
  const page = (
    <GraphQLContext.Provider value={graphql}>
      <App />
    </GraphQLContext.Provider>
  )
  const html = await ssr(graphql, page, ReactDOMServer.renderToString)
  const cache = JSON.stringify(graphql.cache)
  return { html, cache }
}

SSR function that resolves a HTML string suitable for a static page.

import { GraphQL, GraphQLContext } from 'graphql-react'
import { ssr } from 'graphql-react/server'
import { App } from './components'

function render() {
  const graphql = new GraphQL()
  const page = (
    <GraphQLContext.Provider value={graphql}>
      <App />
    </GraphQLContext.Provider>
  )
  return ssr(graphql, page)
}

---

function useGraphQL

A React hook to manage a GraphQL operation in a component.

Parameter	Type	Description
options	Object	Options.
options.fetchOptionsOverride	GraphQLFetchOptionsOverride?	Overrides default fetch options for the GraphQL operation.
options.loadOnMount	boolean? = true	Should the operation load when the component mounts.
options.loadOnReload	boolean? = true	Should the operation load when the GraphQL reload event fires, if the operation was not the one that caused the reload.
options.loadOnReset	boolean? = true	Should the operation load when its GraphQL cache value is reset, if the operation was not the one that caused the reset.
options.reloadOnLoad	boolean? = false	Should a GraphQL reload happen after the operation loads, excluding the loaded operation cache.
options.resetOnLoad	boolean? = false	Should a GraphQL reset happen after the operation loads, excluding the loaded operation cache.
options.operation	GraphQLOperation	GraphQL operation.

Returns: GraphQLOperationStatus — GraphQL operation status.

See

• GraphQLContext Provider; required for useGraphQL to work.

Examples

A component that displays a Pokémon image.

import { useGraphQL } from 'graphql-react'

const PokemonImage = ({ name }) => {
  const { loading, cacheValue = {} } = useGraphQL({
    fetchOptionsOverride(options) {
      options.url = 'https://graphql-pokemon.now.sh'
    },
    operation: {
      query: `{ pokemon(name: "${name}") { image } }`
    }
  })

  return cacheValue.data ? (
    <img src={cacheValue.data.pokemon.image} alt={name} />
  ) : loading ? (
    'Loading…'
  ) : (
    'Error!'
  )
}

---

constant GraphQLContext

React context object for a GraphQL instance.

Type: Object

Property	Type	Description
Provider	function	React context provider component. Enables use of the useGraphQL hook in descendant components.
Consumer	function	React context consumer component.

See

• useGraphQL React hook requires a GraphQLContext Provider to work.

Examples

Provide a GraphQL instance for an app.

import { GraphQL, GraphQLContext } from 'graphql-react'

const graphql = new GraphQL()

const App = ({ children }) => (
  <GraphQLContext.Provider value={graphql}>
    {children}
  </GraphQLContext.Provider>
)

A button component that resets the GraphQL cache.

import { GraphQLContext } from 'graphql-react'

const ResetCacheButton = () => (
  <GraphQLContext.Consumer>
    {graphql => <button onClick={graphql.reset}>Reset cache</button>}
  </GraphQLContext.Consumer>
)

---

type GraphQLCache

A GraphQL cache map of GraphQL operation results.

Type: Object<GraphQLCacheKey, GraphQLCacheValue>

See

• GraphQL constructor accepts this type in options.cache.
• GraphQL instance property cache is this type.

---

type GraphQLCacheKey

A GraphQL cache key, derived from a hash of the fetch options of the GraphQL operation that populated the value.

Type: string

---

type GraphQLCacheValue

JSON serializable GraphQL operation result that includes errors and data.

Type: Object

Property	Type	Description
fetchError	string?	fetch error message.
httpError	HttpError?	fetch response HTTP error.
parseError	string?	Parse error message.
graphQLErrors	Array<Object>?	GraphQL response errors.
data	Object?	GraphQL response data.

---

type GraphQLFetchOptions

GraphQL API URL and polyfillable fetch options. The url property gets extracted and the rest are used as fetch options.

Type: Object

Property	Type	Description
url	string	GraphQL API URL.
body	string | FormData	HTTP request body.
headers	Object	HTTP request headers.
credentials	string?	Authentication credentials mode.

See

• GraphQLFetchOptionsOverride functions accept this type.

---

type GraphQLFetchOptionsOverride

Overrides default GraphQL fetch options. Mutate the provided options object; there is no need to return it.

Type: function

Parameter	Type	Description
options	GraphQLFetchOptions	GraphQL fetch options tailored to the GraphQL operation, e.g. if there are files to upload options.body will be a FormData instance conforming to the GraphQL multipart request spec.

See

• GraphQL instance method operate accepts this type in options.fetchOptionsOverride.
• useGraphQL React hook accepts this type in options.fetchOptionsOverride.

Examples

Setting GraphQL fetch options for an imaginary API.

options => {
  options.url = 'https://api.example.com/graphql'
  options.credentials = 'include'
}

---

type GraphQLOperation

A GraphQL operation. Additional properties may be used; all are sent to the GraphQL server.

Type: Object

Property	Type	Description
query	string	GraphQL queries/mutations.
variables	Object	Variables used in the query.

See

• GraphQL instance method operate accepts this type in options.operation.
• useGraphQL React hook accepts this type in options.operation.

---

type GraphQLOperationLoading

A loading GraphQL operation.

Type: Object

Property	Type	Description
cacheKey	GraphQLCacheKey	GraphQL cache key.
cacheValue	GraphQLCacheValue?	GraphQL cache value from the last identical query.
cacheValuePromise	Promise<GraphQLCacheValue>	Resolves the loaded GraphQL cache value.

See

• GraphQL instance method operate returns this type.

---

type GraphQLOperationStatus

The status of a GraphQL operation.

Type: Object

Property	Type	Description
load	function	Loads the GraphQL operation on demand, updating the GraphQL cache.
loading	boolean	Is the GraphQL operation loading.
cacheKey	GraphQLCacheKey	GraphQL cache key.
cacheValue	GraphQLCacheValue	GraphQL cache value.

See

• useGraphQL React hook returns this type.

---

type HttpError

fetch HTTP error.

Type: Object

Property	Type	Description
status	number	HTTP status code.
statusText	string	HTTP status text.

---

type ReactNode

A React virtual DOM node; anything that can be rendered.

Type: undefined | null | boolean | number | string | React.Element | Array<ReactNode>

Changelog

8.1.3

Patch

• Updated dependencies.
• Adopted the new size-limit config file name.
• Slightly faster useGraphQL render error when options reloadOnLoad and resetOnLoad are both true.
• Use a ref instead of a variable in useGraphQL to track mounted status for cache related callbacks.
• Document the GraphQL instance method operate option reloadOnLoad.
• Minor readme quotes consistency tweak.