Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →

graphql-react

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

graphql-react

A GraphQL client for React using modern context and hooks APIs that’s lightweight (< 3.5 KB) but powerful; the first Relay and Apollo alternative with server side rendering.

13.0.0
Source
npm

Version published: 4 years ago

Weekly downloads: 1.9K; increased by54.71%

Maintainers: 1

Weekly downloads

Created: 7 years ago

Source

graphql-react

A GraphQL client for React using modern context and hooks APIs that’s lightweight (< 3.5 KB) but powerful; the first Relay and Apollo alternative with server side rendering.

The API can also be used to custom load, cache and server side render any data, even from non GraphQL sources.

Setup

First, polyfill any required globals (see Support) that are missing in your server and client environments.

Next.js setup

See the next-graphql-react setup instructions.

Custom React setup

To install graphql-react from npm run:

npm install graphql-react

Create a single Cache instance and use the Provider component to provide it for your app.

To server side render your app, use the waterfallRender function from react-waterfall-render.

Examples

Official Next.js example.
Next.js example deployed at graphql-react.now.sh.

Here is a basic example using the GitHub GraphQL API, with tips commented:

// While named imports are available, deep imports result in a small bundle size
// regardless of the (often dubious) tree-shaking abilities of your bundler.
import useAutoLoad from 'graphql-react/public/useAutoLoad.js';
import useCacheEntry from 'graphql-react/public/useCacheEntry.js';
import useLoadGraphQL from 'graphql-react/public/useLoadGraphQL.js';
import useWaterfallLoad from 'graphql-react/public/useWaterfallLoad.js';
import { useCallback } from 'react';

// The query is just a string; no need to use `gql` from `graphql-tag`. The
// special comment before the string allows editor syntax highlighting, Prettier
// formatting and linting. The cache system doesn’t require `__typename` or `id`
// fields to be queried.
const query = /* GraphQL */ `
  query($repoId: ID!) {
    repo: node(id: $repoId) {
      ... on Repository {
        stargazers {
          totalCount
        }
      }
    }
  }
`;

export default function GitHubRepoStars({ repoId }) {
  const cacheKey = `GitHubRepoStars-${repoId}`;
  const cacheValue = useCacheEntry(cacheKey);

  // A hook for loading GraphQL is available, but custom hooks for loading non
  // GraphQL (e.g. fetching from a REST API) can be made.
  const loadGraphQL = useLoadGraphQL();

  const load = useCallback(
    () =>
      // To be DRY, utilize a custom hook for each API your app loads from, e.g.
      // `useLoadGraphQLGitHub`.
      loadGraphQL(
        cacheKey,
        // Fetch URI.
        'https://api.github.com/graphql',
        // Fetch options.
        {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            Accept: 'application/json',
            Authorization: `Bearer ${process.env.GITHUB_ACCESS_TOKEN}`,
          },
          body: JSON.stringify({
            query,
            variables: {
              repoId,
            },
          }),
        }
      ),
    [cacheKey, loadGraphQL, repoId]
  );

  // This hook automatically keeps the cache entry loaded from when the
  // component mounts, reloading it if it’s staled or deleted. It also aborts
  // loading if the arguments change or the component unmounts; very handy for
  // auto-suggest components!
  useAutoLoad(cacheKey, load);

  // Waterfall loading can be used to load data when server side rendering,
  // enabled automagically by `next-graphql-react`. To learn how this works or
  // to set it up for a non Next.js app, see:
  // https://github.com/jaydenseric/react-waterfall-render
  const isWaterfallLoading = useWaterfallLoad(cacheKey, load);

  // When waterfall loading it’s efficient to skip rendering, as the app will
  // re-render once this step of the waterfall has loaded. If more waterfall
  // loading happens in children, those steps of the waterfall are awaited and
  // the app re-renders again, and so forth until there’s no more loading for
  // the final server side render.
  return isWaterfallLoading
    ? null
    : cacheValue
    ? cacheValue.errors
      ? // Unlike many other GraphQL libraries, detailed loading errors are
        // cached and can be server side rendered without causing a
        // server/client HTML mismatch error.
        'Error!'
      : cacheValue.data.repo.stargazers.totalCount
    : // In this situation no cache value implies loading. Use the
      // `useLoadingEntry` hook to manage loading in detail.
      'Loading…';
}

Support

Node.js: ^12.0.0 || >= 13.7.0
Browsers: > 0.5%, not OperaMini all, not IE > 0, not dead

Consider polyfilling:

API

class Cache

Cache store.

Parameter	Type	Description
`store`	object? = {}	Initial cache store. Useful for hydrating cache data from a server side render prior to the initial client side render.

Examples

Ways to import.

import { Cache } from 'graphql-react';

import Cache from 'graphql-react/public/Cache.js';

Ways to require.

const { Cache } = require('graphql-react');

const Cache = require('graphql-react/public/Cache');

Construct a new instance.

const cache = new Cache();

Cache instance property store

Store of cache keys and values.

Type: object

Cache event delete

Signals that a cache store entry was deleted. The event name starts with the cache key of the deleted entry, followed by /delete.

Type: CustomEvent

Cache event prune

Signals that a cache store entry will be deleted unless the event is canceled via event.preventDefault(). The event name starts with the cache key of the entry being pruned, followed by /prune.

Type: CustomEvent

Cache event set

Signals that a cache store entry was set. The event name starts with the cache key of the set entry, followed by /set.

Type: CustomEvent

Property	Type	Description
`detail`	object	Event detail.
`detail.cacheValue`	CacheValue	Cache value that was set.

Cache event stale

Signals that a cache store entry is now stale (often due to a mutation) and should probably be reloaded. The event name starts with the cache key of the stale entry, followed by /stale.

Type: CustomEvent

class Loading

Loading store.

Examples

Ways to import.

import { Loading } from 'graphql-react';

import Loading from 'graphql-react/public/Loading.js';

Ways to require.

const { Loading } = require('graphql-react');

const Loading = require('graphql-react/public/Loading');

Construct a new instance.

const loading = new Loading();

Loading instance property store

Loading store, keyed by cache key. Multiple loading cache values for the same key are set in the order they started.

Type: object<CacheKey, Set<LoadingCacheValue>>

Loading event end

Signals the end of loading a cache value; either the loading finished and the cache value was set, the loading was aborted, or there was an error. The event name starts with the cache key, followed by /end.

Type: CustomEvent

Property	Type	Description
`detail`	object	Event detail.
`detail.loadingCacheValue`	LoadingCacheValue	Loading cache value that ended.

Loading event start

Signals the start of loading a cache value. The event name starts with the cache key, followed by /start.

Type: CustomEvent

Property	Type	Description
`detail`	object	Event detail.
`detail.loadingCacheValue`	LoadingCacheValue	Loading cache value that started.

class LoadingCacheValue

Controls a loading cache value.

Parameter	Type	Description
`loading`	Loading	Loading to update.
`cache`	Cache	Cache to update.
`cacheKey`	CacheKey	Cache key.
`loadingResult`	Promise<CacheValue>	Resolves the loading result (including any loading errors) to be set as the cache value if loading isn’t aborted. Shouldn’t reject.
`abortController`	AbortController	Aborts this loading and skips setting the loading result as the cache value. Has no affect after loading ends.

Fires

Examples

Ways to import.

import { LoadingCacheValue } from 'graphql-react';

import LoadingCacheValue from 'graphql-react/public/LoadingCacheValue.js';

Ways to require.

const { LoadingCacheValue } = require('graphql-react');

const LoadingCacheValue = require('graphql-react/public/LoadingCacheValue');

LoadingCacheValue instance property abortController

Aborts this loading and skips setting the loading result as the cache value. Has no affect after loading ends.

Type: AbortController

LoadingCacheValue instance property promise

Resolves the loading result, after the cache value has been set if the loading wasn’t aborted. Shouldn’t reject.

Type: Promise<*>

LoadingCacheValue instance property timeStamp

When this loading started.

Type: HighResTimeStamp

function cacheDelete

Deletes cache entries. Useful after a user logs out.

Parameter	Type	Description
`cache`	Cache	Cache to update.
`cacheKeyMatcher`	CacheKeyMatcher?	Matches cache keys to delete. By default all are matched.

Fires

Cache event delete

Examples

Ways to import.

import { cacheDelete } from 'graphql-react';

import cacheDelete from 'graphql-react/public/cacheDelete.js';

Ways to require.

const { cacheDelete } = require('graphql-react');

const cacheDelete = require('graphql-react/public/cacheDelete');

function cacheEntryDelete

Deletes a cache entry.

Parameter	Type	Description
`cache`	Cache	Cache to update.
`cacheKey`	CacheKey	Cache key.

Fires

Cache event delete

Examples

Ways to import.

import { cacheEntryDelete } from 'graphql-react';

import cacheEntryDelete from 'graphql-react/public/cacheEntryDelete.js';

Ways to require.

const { cacheEntryDelete } = require('graphql-react');

const cacheEntryDelete = require('graphql-react/public/cacheEntryDelete');

function cacheEntryPrune

Prunes a cache entry, if no prune event listener cancels the cache entry deletion via event.preventDefault().

Parameter	Type	Description
`cache`	Cache	Cache to update.
`cacheKey`	CacheKey	Cache key.

Fires

Examples

Ways to import.

import { cacheEntryPrune } from 'graphql-react';

import cacheEntryPrune from 'graphql-react/public/cacheEntryPrune.js';

Ways to require.

const { cacheEntryPrune } = require('graphql-react');

const cacheEntryPrune = require('graphql-react/public/cacheEntryPrune');

function cacheEntrySet

Sets a cache entry.

Parameter	Type	Description
`cache`	Cache	Cache to update.
`cacheKey`	CacheKey	Cache key.
`cacheValue`	CacheValue	Cache value.

Fires

Cache event set

Examples

Ways to import.

import { cacheEntrySet } from 'graphql-react';

import cacheEntrySet from 'graphql-react/public/cacheEntrySet.js';

Ways to require.

const { cacheEntrySet } = require('graphql-react');

const cacheEntrySet = require('graphql-react/public/cacheEntrySet');

function cacheEntryStale

Stales a cache entry, signalling it should probably be reloaded.

Parameter	Type	Description
`cache`	Cache	Cache to update.
`cacheKey`	CacheKey	Cache key.

Fires

Cache event stale

Examples

Ways to import.

import { cacheEntryStale } from 'graphql-react';

import cacheEntryStale from 'graphql-react/public/cacheEntryStale.js';

Ways to require.

const { cacheEntryStale } = require('graphql-react');

const cacheEntryStale = require('graphql-react/public/cacheEntryStale');

function cachePrune

Prunes cache entries. Useful after a mutation.

Parameter	Type	Description
`cache`	Cache	Cache to update.
`cacheKeyMatcher`	CacheKeyMatcher?	Matches cache keys to prune. By default all are matched.

Fires

Examples

Ways to import.

import { cachePrune } from 'graphql-react';

import cachePrune from 'graphql-react/public/cachePrune.js';

Ways to require.

const { cachePrune } = require('graphql-react');

const cachePrune = require('graphql-react/public/cachePrune');

function cacheStale

Stales cache entries. Useful after a mutation.

Parameter	Type	Description
`cache`	Cache	Cache to update.
`cacheKeyMatcher`	CacheKeyMatcher?	Matches cache keys to stale. By default all are matched.

Fires

Cache event stale

Examples

Ways to import.

import { cacheStale } from 'graphql-react';

import cacheStale from 'graphql-react/public/cacheStale.js';

Ways to require.

const { cacheStale } = require('graphql-react');

const cacheStale = require('graphql-react/public/cacheStale');

function fetchGraphQL

Fetches a GraphQL operation, always resolving a GraphQL result suitable for use as a cache value, even if there are errors. Loading errors are added to the GraphQL result errors property, and have an extensions property containing client: true, along with code and sometimes error-specific properties:

Error code	Reasons	Error specific properties
`FETCH_ERROR`	Fetch error, e.g. the `fetch` global isn’t defined, or the network is offline.	`fetchErrorMessage` (string).
`RESPONSE_HTTP_STATUS`	Response HTTP status code is in the error range.	`statusCode` (number), `statusText` (string).
`RESPONSE_JSON_PARSE_ERROR`	Response JSON parse error.	`jsonParseErrorMessage` (string).
`RESPONSE_MALFORMED`	Response JSON isn’t an object, is missing an `errors` or `data` property, the `errors` property isn’t an array, or the `data` property isn’t an object or `null`.

Parameter	Type	Description
`fetchUri`	string	Fetch URI for the GraphQL API.
`fetchOptions`	FetchOptions	Fetch options.

Returns: Promise<GraphQLResult> — Resolves a result suitable for use as a cache value. Shouldn’t reject.

Examples

Ways to import.

import { fetchGraphQL } from 'graphql-react';

import fetchGraphQL from 'graphql-react/public/fetchGraphQL.js';

Ways to require.

const { fetchGraphQL } = require('graphql-react');

const fetchGraphQL = require('graphql-react/public/fetchGraphQL');

function fetchOptionsGraphQL

Creates default fetch options for a GraphQL operation. If the GraphQL operation contains files to upload, the options will be for a GraphQL multipart request, otherwise they will be for a regular GraphQL POST request.

This utility exists for user convenience and isn’t used directly by the graphql-react API. If there is no chance the GraphQL operation contains files, avoid using this utility for a smaller bundle size.

Parameter	Type	Description
`operation`	GraphQLOperation	GraphQL operation.

Returns: FetchOptions — fetch options.

Examples

Ways to import.

import { fetchOptionsGraphQL } from 'graphql-react';

import fetchOptionsGraphQL from 'graphql-react/public/fetchOptionsGraphQL.js';

Ways to require.

const { fetchOptionsGraphQL } = require('graphql-react');

const fetchOptionsGraphQL = require('graphql-react/public/fetchOptionsGraphQL');

function Provider

A React component to provide all the React context required to enable the entire graphql-react API:

Parameter	Type	Description
`props`	object	Component props.
`props.cache`	Cache	`Cache` instance.
`props.children`	ReactNode?	React children.

Returns: ReactNode — React virtual DOM node.

Examples

Ways to import.

import { Provider } from 'graphql-react';

import Provider from 'graphql-react/public/Provider.js';

Ways to require.

const { Provider } = require('graphql-react');

const Provider = require('graphql-react/public/Provider');

Provide a Cache instance for an app.

import { Cache, Provider } from 'graphql-react';
import React from 'react';

const cache = new Cache();

const App = ({ children }) => <Provider cache={cache}>{children}</Provider>;

function useAutoAbortLoad

A React hook to create a memoized loader from another, that automatically aborts previous loading that started via this hook when new loading starts via this hook, the hook arguments change, or the component unmounts.

Parameter	Type	Description
`load`	Loader	Memoized function that starts the loading.

Returns: Loader — Memoized function that starts the loading.

Examples

Ways to import.

import { useAutoAbortLoad } from 'graphql-react';

import useAutoAbortLoad from 'graphql-react/public/useAutoAbortLoad.js';

Ways to require.

const { useAutoAbortLoad } = require('graphql-react');

const useAutoAbortLoad = require('graphql-react/public/useAutoAbortLoad');

function useAutoLoad

A React hook to prevent a cache entry from being pruned while the component is mounted and automatically keep it loaded. Previous loading that started via this hook aborts when new loading starts via this hook, the hook arguments change, or the component unmounts.

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key.
`load`	Loader	Memoized function that starts the loading.

Returns: Loader — Memoized loader created from the load argument, that automatically aborts the last loading when the memoized function changes or the component unmounts.

See

useCacheEntryPrunePrevention, used by this hook.
useAutoAbortLoad, used by this hook.
useLoadOnMount, used by this hook.
useLoadOnStale, used by this hook.
useLoadOnDelete, used by this hook.
useWaterfallLoad, often used alongside this hook for SSR loading.

Examples

Ways to import.

import { useAutoLoad } from 'graphql-react';

import useAutoLoad from 'graphql-react/public/useAutoLoad.js';

Ways to require.

const { useAutoLoad } = require('graphql-react');

const useAutoLoad = require('graphql-react/public/useAutoLoad');

function useCache

A React hook to get the cache context.

Returns: Cache — The cache.

Examples

Ways to import.

import { useCache } from 'graphql-react';

import useCache from 'graphql-react/public/useCache.js';

Ways to require.

const { useCache } = require('graphql-react');

const useCache = require('graphql-react/public/useCache');

function useCacheEntry

A React hook to get a cache value using its cache key.

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key.

Returns: CacheValue — Cache value, if present.

Examples

Ways to import.

import { useCacheEntry } from 'graphql-react';

import useCacheEntry from 'graphql-react/public/useCacheEntry.js';

Ways to require.

const { useCacheEntry } = require('graphql-react');

const useCacheEntry = require('graphql-react/public/useCacheEntry');

function useCacheEntryPrunePrevention

A React hook to prevent a cache entry from being pruned, by canceling the cache entry deletion for prune events with event.preventDefault().

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key.

Examples

Ways to import.

import { useCacheEntryPrunePrevention } from 'graphql-react';

import useCacheEntryPrunePrevention from 'graphql-react/public/useCacheEntryPrunePrevention.js';

Ways to require.

const { useCacheEntryPrunePrevention } = require('graphql-react');

const useCacheEntryPrunePrevention = require('graphql-react/public/useCacheEntryPrunePrevention');

function useLoadGraphQL

A React hook to get a function for loading a GraphQL operation.

Returns: LoadGraphQL — Loads a GraphQL operation.

Examples

Ways to import.

import { useLoadGraphQL } from 'graphql-react';

import useLoadGraphQL from 'graphql-react/public/useLoadGraphQL.js';

Ways to require.

const { useLoadGraphQL } = require('graphql-react');

const useLoadGraphQL = require('graphql-react/public/useLoadGraphQL');

function useLoading

A React hook to get the loading context.

Returns: Loading — Loading.

Examples

Ways to import.

import { useLoading } from 'graphql-react';

import useLoading from 'graphql-react/public/useLoading.js';

Ways to require.

const { useLoading } = require('graphql-react');

const useLoading = require('graphql-react/public/useLoading');

function useLoadingEntry

A React hook to get the loading cache values for a given cache key.

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key.

Returns: Set<LoadingCacheValue> | undefined — Loading cache values, if present.

Examples

Ways to import.

import { useLoadingEntry } from 'graphql-react';

import useLoadingEntry from 'graphql-react/public/useLoadingEntry.js';

Ways to require.

const { useLoadingEntry } = require('graphql-react');

const useLoadingEntry = require('graphql-react/public/useLoadingEntry');

function useLoadOnDelete

A React hook to load a cache entry after it’s deleted, if there isn’t loading for the cache key that started after.

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key.
`load`	Loader	Memoized function that starts the loading.

Examples

Ways to import.

import { useLoadOnDelete } from 'graphql-react';

import useLoadOnDelete from 'graphql-react/public/useLoadOnDelete.js';

Ways to require.

const { useLoadOnDelete } = require('graphql-react');

const useLoadOnDelete = require('graphql-react/public/useLoadOnDelete');

function useLoadOnMount

A React hook to automatically load a cache entry after the component mounts or the cache context or any of the arguments change, except during the hydration time if the hydration time stamp context is populated and the cache entry is already populated.

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key.
`load`	Loader	Memoized function that starts the loading.

Examples

Ways to import.

import { useLoadOnMount } from 'graphql-react';

import useLoadOnMount from 'graphql-react/public/useLoadOnMount.js';

Ways to require.

const { useLoadOnMount } = require('graphql-react');

const useLoadOnMount = require('graphql-react/public/useLoadOnMount');

function useLoadOnStale

A React hook to load a cache entry after becomes stale, if there isn’t loading for the cache key that started after.

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key.
`load`	Loader	Memoized function that starts the loading.

Examples

Ways to import.

import { useLoadOnStale } from 'graphql-react';

import useLoadOnStale from 'graphql-react/public/useLoadOnStale.js';

Ways to require.

const { useLoadOnStale } = require('graphql-react');

const useLoadOnStale = require('graphql-react/public/useLoadOnStale');

function useWaterfallLoad

A React hook to load a cache entry if the waterfall render context is populated, i.e. when waterfall rendering for either a server side render or to preload components in a browser environment.

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key.
`load`	Loader	Memoized function that starts the loading.

Returns: boolean — Did loading start. If so, it’s efficient for the component to return null since this render will be discarded anyway for a re-render onces the loading ends.

See

useAutoLoad, often used alongside this hook.

Examples

Ways to import.

import { useWaterfallLoad } from 'graphql-react';

import useWaterfallLoad from 'graphql-react/public/useWaterfallLoad.js';

Ways to require.

const { useWaterfallLoad } = require('graphql-react');

const useWaterfallLoad = require('graphql-react/public/useWaterfallLoad');

member CacheContext

React context for a Cache instance.

Type: object

Property	Type	Description
`Provider`	Function	React context provider component.
`Consumer`	Function	React context consumer component.

Examples

Ways to import.

import { CacheContext } from 'graphql-react';

import CacheContext from 'graphql-react/public/CacheContext.js';

Ways to require.

const { CacheContext } = require('graphql-react');

const CacheContext = require('graphql-react/public/CacheContext');

member HydrationTimeStampContext

React context for the client side hydration time stamp.

Type: object

Property	Type	Description
`Provider`	Function	React context provider component.
`Consumer`	Function	React context consumer component.

Examples

Ways to import.

import { HydrationTimeStampContext } from 'graphql-react';

import HydrationTimeStampContext from 'graphql-react/public/HydrationTimeStampContext.js';

Ways to require.

const { HydrationTimeStampContext } = require('graphql-react');

const HydrationTimeStampContext = require('graphql-react/public/HydrationTimeStampContext');

member LoadingContext

React context for a Loading instance.

Type: object

Property	Type	Description
`Provider`	Function	React context provider component.
`Consumer`	Function	React context consumer component.

Examples

Ways to import.

import { LoadingContext } from 'graphql-react';

import LoadingContext from 'graphql-react/public/LoadingContext.js';

Ways to require.

const { LoadingContext } = require('graphql-react');

const LoadingContext = require('graphql-react/public/LoadingContext');

constant HYDRATION_TIME_MS

Number of milliseconds after the first client render that’s considered the hydration time; during which the useAutoLoad React hook won’t load if the cache entry is already populated.

Type: number

Examples

Ways to import.

import { HYDRATION_TIME_MS } from 'graphql-react';

import HYDRATION_TIME_MS from 'graphql-react/public/HYDRATION_TIME_MS.js';

Ways to require.

const { HYDRATION_TIME_MS } = require('graphql-react');

const HYDRATION_TIME_MS = require('graphql-react/public/HYDRATION_TIME_MS');

type CacheKey

A unique key to access a cache value.

Type: string

type CacheKeyMatcher

Matches a cache key against a custom condition.

Type: Function

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key.

Returns: boolean — Does the cache key match the custom condition.

type CacheValue

A cache value. If server side rendering, it should be JSON serializable for client hydration. It should contain information about any errors that occurred during loading so they can be rendered, and if server side rendering, be hydrated on the client.

Type: *

type FetchOptions

fetch options, called init in official specs.

Type: object

See

MDN fetch parameters docs.
Polyfillable fetch options. Don’t use other options if fetch is polyfilled for Node.js or legacy browsers.

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 or mutations.
`variables`	object?	Variables used in the `query`.

type GraphQLResult

A GraphQL result.

Type: object

Property	Type	Description
`data`	object?	GraphQL response data.
`errors`	Array<GraphQLResultError>?	GraphQL response errors from the server, along with any loading errors added on the client.

See

GraphQL spec for a response.

type GraphQLResultError

A GraphQL result error; either created by the GraphQL server, or by whatever loaded the GraphQL on the client (e.g. fetchGraphQL).

Type: object

Property	Type	Description
`message`	object	Error message.
`locations`	Array<{line: number, column: number}>?	GraphQL query locations related to the error.
`path`	Array?	GraphQL result `data` field path related to the error.
`extensions`	object?	Custom error data. If the error was created on the client and not the GraphQL server, this property should be present and contain at least `client: true`, although `code` and error specific properties may be present.

See

GraphQL spec for response errors.

type HighResTimeStamp

Milliseconds since the performance time origin (when the current JavaScript environment started running).

Type: number

See

MDN DOMHighResTimeStamp docs.

type Loader

Starts loading a cache value.

Type: Function

Returns: LoadingCacheValue — The loading cache value.

type LoadGraphQL

Loads a GraphQL operation, using the GraphQL fetcher.

Type: Loader

Parameter	Type	Description
`cacheKey`	CacheKey	Cache key to store the loading result under.
`fetchUri`	string	`fetch` URI.
`fetchOptions`	FetchOptions	`fetch` options.

Returns: LoadingCacheValue — The loading cache value.

type ReactNode

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

13.0.0

Major

Updated Node.js version support to ^12.0.0 || >= 13.7.0.
Stopped supporting Internet Explorer.
Updated the react and react-dom peer dependencies to 16.14 - 17.
Use the new JSX runtime.
Reorganized the file structure and replaced the entire API:
- Removed all of the previous public exports for the old API:
  - GraphQL
  - GraphQLContext
  - GraphQLProvider
  - hashObject
  - reportCacheErrors
  - useGraphQL
  - ssr
- Added public exports for the new API, available as named imports from the index and as deep imports from graphql-react/public/ .js CJS modules:
  - Cache
  - CacheContext
  - HYDRATION_TIME_MS
  - HydrationTimeStampContext
  - Loading
  - LoadingCacheValue
  - LoadingContext
  - Provider
  - cacheDelete
  - cacheEntryDelete
  - cacheEntryPrune
  - cacheEntrySet
  - cacheEntryStale
  - cachePrune
  - cacheStale
  - fetchGraphQL
  - fetchOptionsGraphQL
  - useAutoAbortLoad
  - useAutoLoad
  - useCache
  - useCacheEntry
  - useCacheEntryPrunePrevention
  - useLoadGraphQL
  - useLoadOnDelete
  - useLoadOnMount
  - useLoadOnStale
  - useLoading
  - useLoadingEntry
  - useWaterfallLoad
- The function waterfallRender from react-waterfall-render should now be used for server side rendering, fixing #57.
- In addition to the previously required globals, consider polyfilling:
The API for the cache (centered around a Cache instance provided in the CacheContext React context) is separated from the API for loading (centered around a Loading instance provided in the LoadingContext React context). Although the new loading system should work well for everyone, it could be totally avoided in an app that implements a custom alternative.

Instead of using the old mitt dependency for events, the Cache and Loading classes extend the native EventTarget global available in modern browsers and Node.js; a powerful and familiar event system with zero bundle size cost.

The new API avoids class methods that add to bundle size regardless if they are used, in favor of focused functions that can be imported to process instances as arguments. For example, one route in your app may only render a cache entry, while another may have a form that makes the global cache stale. If the functionality to make the cache stale was a Cache instance method, it would increase the bundle size for the entire app, whereas a function imported in the second route will only grow the bundle size for that route. Features can be added to the API over time without growing everyone’s bundles.

There are now functions that can be imported to directly manipulate the cache. The functions cacheEntrySet and cacheEntryDelete update a particular entry, and cacheDelete deletes all cache.

There is a new approach for dealing with stale cache. The function cacheEntryStale signals a single entry is stale, and cacheStale does the same for all entries (useful after a mutation). These functions don’t actually update cache entries; they simply dispatch cache entry stale events and it’s up to components to listen for this event and reload the cache entry in response, typically via the useLoadOnStale React hook.

Cache entries that are not relevant to the current view can now be pruned on demand using the functions cacheEntryPrune for a single entry, or cachePrune for all entries, fixing #55. These functions work by dispatching cache entry prune events on the Cache instance, and for each event not cancelled by a listener with event.preventDefault(), the cache entry is deleted. The useCacheEntryPrunePrevention React hook can be used to automatically cancel pruning of a cache entry used in a component.

Cache keys are now manually defined instead of automatically derived from fetch options hashes, fixing #56. This is easier to understand, is faster to render, and results in a smaller bundle size without the old fnv1a dependency for hashing.

Instead of one useGraphQL React hook with complex options that all add to a component’s bundle size regardless if they are used, there are now several more focused React hooks that can be composed to do exactly the work required, fixing #53.

The React hooks can be composed with custom ones to load and cache any type of data, not just GraphQL, using any method, not just fetch.

The new loading system provides the ability to abort loading at any time, implemented using the native AbortController global available in modern browsers and Node.js, fixing #24. Many of the new React hooks leverage this for features such as automatically aborting loading a cache entry when the component loading it unmounts. The new API makes it trivially easy to build features as auto-suggest search inputs that abort the last loading on new input, or page queries that abort loading if the user abandons the route.

While the new API may seem to have an intimidating number of public exports, the average Next.js app that queries and renders data from a GraphQL API will only use a few. For inspiration, see the readme “Examples” section.
Published modules now contain JSDoc comments, which might affect TypeScript projects.

Patch

Updated dependencies.
Removed Babel and related dependencies and config.
Updated GitHub Actions CI config:
- Updated actions/checkout to v2.
- Updated actions/setup-node to v2.
- Don’t specify the CI environment variable as it’s set by default.
Stop using hard-rejection to detect unhandled Promise rejections in tests, as Node.js v15+ does this natively.
Test the bundle size manually using webpack v5, and remove size-limit related dev dependencies, config, and scripts.
Tweaked the package description.
Readme edits, including:
- Updated the Relay and Apollo URLs.
- Mention polyfilling any required globals in the “Setup” section.
- Removed the “Usage” section.
- Tweaked links in the “Support” section.
- Removed the “Apollo comparison” section.

Keywords

FAQs

What is graphql-react?

Is graphql-react popular?

Is graphql-react well maintained?

Package last updated on 19 Apr 2021

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.

Install

graphql-react

graphql-react

Setup

Next.js setup

Custom React setup

Examples

Support

API

Table of contents

class Cache

Examples

Cache instance property store

Cache event delete

Cache event prune

Cache event set

Cache event stale

class Loading

Examples

Loading instance property store

Loading event end

Loading event start

class LoadingCacheValue

Fires

Examples

LoadingCacheValue instance property abortController

LoadingCacheValue instance property promise

LoadingCacheValue instance property timeStamp

function cacheDelete

Fires

Examples

function cacheEntryDelete

Fires

Examples

function cacheEntryPrune

Fires

Examples

function cacheEntrySet

Fires

Examples

function cacheEntryStale

Fires

Examples

function cachePrune

Fires

Examples

function cacheStale

Fires

Examples

function fetchGraphQL

Examples

function fetchOptionsGraphQL

Examples

function Provider

Examples

function useAutoAbortLoad

Examples

function useAutoLoad

See

Examples

function useCache

Examples

function useCacheEntry

Examples

function useCacheEntryPrunePrevention

Examples

function useLoadGraphQL

Examples

function useLoading

Examples

function useLoadingEntry

Examples

function useLoadOnDelete

Examples

function useLoadOnMount

Examples

function useLoadOnStale

Examples

function useWaterfallLoad

See

Examples