graphql-react

graphql-react

A lightweight GraphQL client for React; the first Relay and Apollo alternative with server side rendering.

Easy 🔥

• Add 1 dependency to get started with GraphQL in a React project.
• No Webpack or Babel setup.
• Simple components, no decorators.
• Query components fetch on mount and when props change. While loading, cache from the last identical request is available to display.
• Automatically fresh cache, even after mutations.
• Use file input values as mutation arguments to upload files; compatible with a variety of servers.
• Template literal queries; no need for gql.
• Query multiple GraphQL APIs.

Smart 💡

• Adds only a few KB to a typical min+gzip bundle.
• Native ESM in Node.js via .mjs.
• Package module entry for tree shaking bundlers.
• Server side rendering for crawlable pages and a better UX.
• Components use the React v16.3 context API.
• All fetch options overridable per request.
• GraphQL request fetch options hash based cache:
  • No data denormalization or need to query id fields.
  • No tampering with queries or __typename insertion.
  • Errors are cached and can be server side rendered.
  • Query multiple GraphQL APIs without stitching data.

Setup

To install graphql-react from npm run:

npm install graphql-react

Create and provide a GraphQL client:

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

const graphql = new GraphQL()

const Page = () => (
  <Provider value={graphql}>Use Consumer or Query components…</Provider>
)

Example

See the example GraphQL API and Next.js web app, deployed at graphql-react.now.sh.

Support

• Node.js v8.5+.
• Browsers >1% usage.

Consider polyfilling:

• Promise
• fetch

API

Table of contents

• class GraphQL
  • Examples
  • GraphQL instance method query
  • GraphQL instance method reset
    • Examples
  • GraphQL instance property cache
    • Examples
• class GraphQLQuery
  • GraphQLQuery instance method load
• function Consumer
  • Examples
• function preload
  • Examples
• function Provider
  • Examples
• function Query
  • Examples
• type ActiveQuery
• type ConsumerRender
  • Examples
• type FetchOptions
• type FetchOptionsOverride
  • Examples
• type HttpError
• type Operation
• type QueryRender
  • Examples
• type RequestCache

class GraphQL

A lightweight GraphQL client that caches requests.

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

Examples

Constructing a new GraphQL client.

import { GraphQL } from 'graphql-react'

const graphql = new GraphQL()

GraphQL instance method query

Queries a GraphQL server.

Parameter	Type	Description
options	Object	Options.
options.operation	Operation	GraphQL operation object.
options.fetchOptionsOverride	FetchOptionsOverride?	Overrides default GraphQL request fetch options.
options.resetOnLoad	boolean? = false	Should the GraphQL cache reset when the query loads.

Returns: ActiveQuery — Loading query details.

GraphQL instance method reset

Resets the GraphQL cache. Useful when a user logs out.

Parameter	Type	Description
exceptFetchOptionsHash	string?	A fetch options hash to exempt a request from cache deletion. Useful for resetting cache after a mutation, preserving the mutation cache.

Examples

Resetting the GraphQL cache.

graphql.reset()

GraphQL instance property cache

GraphQL request cache map, keyed by fetch options hashes.

Examples

Export cache as JSON.

const exportedCache = JSON.stringify(graphql.cache)

class GraphQLQuery

A React component to manage a GraphQL query with a GraphQL instance. See also the Query component, which takes the GraphQL instance from context instead of a prop.

Parameter	Type	Description
props	Object	Component props.
props.graphql	GraphQL	GraphQL instance.
props.variables	Object?	GraphQL query variables.
props.query	string	GraphQL query.
props.fetchOptionsOverride	FetchOptionsOverride?	Overrides default fetch options for the GraphQL request.
props.loadOnMount	boolean? = false	Should the query load when the component mounts.
props.loadOnReset	boolean? = false	Should the query load when its GraphQL cache entry is reset.
props.resetOnLoad	boolean? = false	Should all other GraphQL cache reset when the query loads.
props.children	QueryRender	Renders the query status.

GraphQLQuery instance method load

Loads the query, updating cache.

Returns: Promise<RequestCache> — A promise that resolves the request cache.

function Consumer

A React component that gets the GraphQL instance from context.

Parameter	Type	Description
children	ConsumerRender	Render function that receives a GraphQL instance.

Returns: ReactElement — React virtual DOM element.

Examples

A button component that resets the GraphQL cache.

import { Consumer } from 'graphql-react'

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

function preload

Recursively preloads Query components that have the loadOnMount prop in a React element tree. Useful for server side rendering (SSR) or to preload components for a better user experience when they mount.

Parameter	Type	Description
element	ReactElement	A React virtual DOM element.

Returns: Promise — Resolves once loading is done and cache is ready to be exported from the GraphQL instance. Cache can be imported when constructing new GraphQL instances.

Examples

An async SSR function that returns a HTML string and cache JSON for client hydration.

import { GraphQL, preload, Provider } from 'graphql-react'
import { renderToString } from 'react-dom/server'
import { App } from './components'

const graphql = new GraphQL()
const page = (
  <Provider value={graphql}>
    <App />
  </Provider>
)

export async function ssr() {
  await preload(page)
  return {
    cache: JSON.stringify(graphql.cache),
    html: renderToString(page)
  }
}

function Provider

A React component that provides a GraphQL instance in context for nested Consumer components to use.

Parameter	Type	Description
value	GraphQL	A GraphQL instance.
children	ReactNode	A React node.

Returns: ReactElement — React virtual DOM element.

Examples

Using the Provider component for a page.

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

const graphql = new GraphQL()

const Page = () => (
  <Provider value={graphql}>Use Consumer or Query components…</Provider>
)

function Query

A React component to manage a GraphQL query or mutation.

Parameter	Type	Description
props	Object	Component props.
props.variables	Object?	GraphQL query variables.
props.query	string	GraphQL query.
props.fetchOptionsOverride	FetchOptionsOverride?	Overrides default GraphQL request fetch options.
props.loadOnMount	boolean? = false	Should the query load when the component mounts.
props.loadOnReset	boolean? = false	Should the query load when the GraphQL cache is reset.
props.resetOnLoad	boolean? = false	Should the GraphQL cache reset when the query loads.
props.children	QueryRender	Renders the query status.

Returns: ReactElement — React virtual DOM element.

Examples

A query to display a user profile.

import { Query } from 'graphql-react'

const Profile = ({ userId }) => (
  <Query
    loadOnMount
    loadOnReset
    fetchOptionsOverride={options => {
      options.url = 'https://api.example.com/graphql'
    }}
    variables={{ userId }}
    query={`
      query user($userId: ID!) {
        user(userId: $id) {
          name
        }
      }
    `}
  >
    {({
      load,
      loading,
      fetchError,
      httpError,
      parseError,
      graphQLErrors,
      data
    }) => (
      <article>
        <button onClick={load}>Reload</button>
        {loading && <span>Loading…</span>}
        {(fetchError || httpError || parseError || graphQLErrors) && (
          <strong>Error!</strong>
        )}
        {data && <h1>{data.user.name}</h1>}
      </article>
    )}
  </Query>
)

A mutation to clap an article.

import { Query } from 'graphql-react'

const ClapArticleButton = ({ articleId }) => (
  <Query
    resetOnLoad
    fetchOptionsOverride={options => {
      options.url = 'https://api.example.com/graphql'
    }}
    variables={{ articleId }}
    query={`
      mutation clapArticle($articleId: ID!) {
        clapArticle(articleId: $id) {
          clapCount
        }
      }
    `}
  >
    {({
      load,
      loading,
      fetchError,
      httpError,
      parseError,
      graphQLErrors,
      data
    }) => (
      <aside>
        <button onClick={load} disabled={loading}>
          Clap
        </button>
        {(fetchError || httpError || parseError || graphQLErrors) && (
          <strong>Error!</strong>
        )}
        {data && <p>Clapped {data.clapArticle.clapCount} times.</p>}
      </aside>
    )}
  </Query>
)

type ActiveQuery

Loading query details.

Type: Object

Property	Type	Description
fetchOptionsHash	string	fetch options hash.
cache	RequestCache?	Results from the last identical request.
request	Promise<RequestCache>	A promise that resolves fresh request cache.

type ConsumerRender

Renders a GraphQL consumer.

Type: function

Parameter	Type	Description
graphql	GraphQL	GraphQL instance.

Returns: ReactElement — React virtual DOM element.

Examples

A button that resets the GraphQL cache.

graphql => <button onClick={graphql.reset}>Reset cache</button>

type FetchOptions

Polyfillable fetch options for a GraphQL request.

Type: Object

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

type FetchOptionsOverride

Overrides default GraphQL request fetch options. Modify the provided options object without a return.

Type: function

Parameter	Type	Description
fetchOptions	FetchOptions	Default GraphQL request fetch options.
operation	Operation?	A GraphQL operation object.

Examples

Setting fetch options for an example API.

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

type HttpError

Fetch HTTP error.

Type: Object

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

type Operation

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

Type: Object

Property	Type	Description
query	string	GraphQL queries or mutations.
variables	Object	Variables used by the query.

type QueryRender

Renders the status of a query or mutation.

Type: function

Parameter	Type	Description
load	function	Loads the query on demand, updating cache.
loading	boolean	Is the query loading.
fetchError	string?	Fetch error message.
httpError	HttpError?	Fetch response HTTP error.
parseError	string?	Parse error message.
graphQLErrors	Object?	GraphQL response errors.
data	Object?	GraphQL response data.

Returns: ReactElement — React virtual DOM element.

Examples

Rendering a user profile query.

;({
  load,
  loading,
  fetchError,
  httpError,
  parseError,
  graphQLErrors,
  data
}) => (
  <aside>
    <button onClick={load}>Reload</button>
    {loading && <span>Loading…</span>}
    {(fetchError || httpError || parseError || graphQLErrors) && (
      <strong>Error!</strong>
    )}
    {data && <h1>{data.user.name}</h1>}
  </aside>
)

type RequestCache

JSON serializable result of a GraphQL request (including all errors and data) suitable for caching.

Type: Object

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

Changelog

2.0.0

Major

• Updated Node.js support from v7.6+ to v8.5+.

Minor

• Use package prepare script to support installation via Git (e.g. npm install jaydenseric/graphql-react).
• Use @babel/plugin-transform-runtime and @babel/runtime to make runtime helpers more DRY. Bundle size savings will manifest once more packages import the same helpers.
• Package marked side-effect free for bundlers and tree-shaking.

Patch

• Updated dependencies.
• Removed the rimraf dev dependency in favour of a native rm -rf package clean script. Leaner and faster; we only support *nix for contributing anyway.
• Fixed new Prettier lint errors and removed the fake-tag dev dependency now that Prettier can format template literals tagged with /* GraphQL */.
• Stopped using npm-run-all for package scripts to reduce complexity and bugs.
• Compact package repository field.
• Added more package tags.
• Lint .yml files.
• Test with graphql-api-koa instead of express-graphql.
• Fixed test snapshot consistency between Node.js versions (see tapjs/node-tap#450).
• Use jsdoc-md instead of documentation to generate readme API docs.
• JSDoc fixes and improvements.
• Readme badge changes to deal with shields.io unreliability:
  • Used the more reliable build status badge provided by Travis, configured to only track master branch.
  • Removed the licence badge. The licence can be found in package.json and rarely changes.
  • Removed the Github issues and stars badges. The readme is most viewed on Github anyway.
  • Use Badgen for the npm version badge.