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
Bundle impact
graphql-react
A < 2 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.
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.
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
Support
- Node.js v8.5+
- Browsers
> 0.5%, not dead
Consider polyfilling:
API
Table of contents
- class GraphQL
- function reportCacheErrors
- function ssr
- function useGraphQL
- constant GraphQLContext
- type GraphQLCache
- type GraphQLCacheKey
- type GraphQLCacheValue
- type GraphQLFetchOptions
- type GraphQLFetchOptionsOverride
- type GraphQLOperation
- type GraphQLOperationLoading
- type GraphQLOperationStatus
- 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.
Parameter | Type | Description |
---|---|---|
options |
Object | Options. |
options.operation |
GraphQLOperation | GraphQL operation. |
options.fetchOptionsOverride |
GraphQLFetchOptionsOverride? | Overrides default GraphQL operation fetch options. |
options.resetOnLoad |
boolean? = false |
Should the GraphQL cache reset when the operation loads. |
Returns: GraphQLOperationLoading — Loading GraphQL operation details.
GraphQL instance method reset
Resets the GraphQL cache. Useful when a user logs out.
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.loadOnReset |
boolean? = true |
Should the operation load when its GraphQL cache value is reset. |
options.resetOnLoad |
boolean? = false |
Should all other GraphQL cache reset when the operation loads. |
options.operation |
GraphQLOperation | GraphQL operation. |
Returns: GraphQLOperationStatus — GraphQL operation status.
See
GraphQLContext
Provider
; required foruseGraphQL
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 aGraphQLContext
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 inoptions.cache
.GraphQL
instance propertycache
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 methodoperate
accepts this type inoptions.fetchOptionsOverride
.useGraphQL
React hook accepts this type inoptions.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 methodoperate
accepts this type inoptions.operation
.useGraphQL
React hook accepts this type inoptions.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 methodoperate
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>