Skip to content
Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
662 lines (509 sloc) 26 KB

graphql-hooks

Join the community on Spectrum CircleCI Coverage Status bundlephobia npm All Contributors lerna

🎣 Minimal hooks-first GraphQL client.

Features

  • πŸ₯‡ First-class hooks API
  • βš–οΈ Tiny bundle: only 5.3kB (1.9 gzipped)
  • πŸ“„ Full SSR support: see graphql-hooks-ssr
  • πŸ”Œ Plugin Caching: see graphql-hooks-memcache
  • πŸ”₯ No more render props hell
  • ⏳ Handle loading and error states with ease

Install

npm install graphql-hooks

or

yarn add graphql-hooks

Support

Consider polyfilling:

Quick Start

First you'll need to create a client and wrap your app with the provider:

import { GraphQLClient, ClientContext } from 'graphql-hooks'

const client = new GraphQLClient({
  url: '/graphql'
})

function App() {
  return (
    <ClientContext.Provider value={client}>
      {/* children */}
    </ClientContext.Provider>
  )
}

Now in your child components you can make use of useQuery

import { useQuery } from 'graphql-hooks'

const HOMEPAGE_QUERY = `query HomePage($limit: Int) {
  users(limit: $limit) {
    id
    name
  }
}`

function MyComponent() {
  const { loading, error, data } = useQuery(HOMEPAGE_QUERY, {
    variables: {
      limit: 10
    }
  })

  if (loading) return 'Loading...'
  if (error) return 'Something Bad Happened'

  return (
    <ul>
      {data.users.map(({ id, name }) => (
        <li key={id}>{name}</li>
      ))}
    </ul>
  )
}

Table of Contents

API

GraphQLClient

Usage:

import { GraphQLClient } from 'graphql-hooks'
const client = new GraphQLClient(config)

config: Object containing configuration properties

  • url (Required): The url to your GraphQL server
  • ssrMode: Boolean - set to true when using on the server for server-side rendering; defaults to false
  • cache (Required if ssrMode is true, otherwise optional): Object with the following methods:
    • cache.get(key)
    • cache.set(key, data)
    • cache.delete(key)
    • cache.clear()
    • cache.keys()
    • getInitialState()
    • See graphql-hooks-memcache as a reference implementation
  • fetch(url, options): Fetch implementation - defaults to the global fetch API
  • fetchOptions: See MDN for info on what options can be passed
  • headers: Object, e.g. { 'My-Header': 'hello' }
  • logErrors: Boolean - defaults to true
  • onError({ operation, result }): Custom error handler
    • operation: Object with query, variables and operationName
    • result: Object containing error, data, fetchError, httpError and graphqlErrors

client methods

  • client.setHeader(key, value): Updates client.headers adding the new header to the existing headers
  • client.setHeaders(headers): Replaces client.headers
  • client.logErrorResult({ operation, result }): Default error logger; useful if you'd like to use it inside your custom onError handler
  • request(operation, options): Make a request to your GraphQL server; returning a Promise
    • operation: Object with query, variables and operationName
  • options.fetchOptionsOverrides: Object containing additional fetch options to be added to the default ones passed to new GraphQLClient(config)

ClientContext

ClientContext is the result of React.createContext() - meaning it can be used directly with React's new context API:

Example:

import { ClientContext } from 'graphql-hooks'

function App() {
  return (
    <ClientContext.Provider value={client}>
      {/* children can now consume the client context */}
    </ClientContext.Provider>
  )
}

To access the GraphQLClient instance, call React.useContext(ClientContext):

import React, { useContext } from 'react'
import { ClientContext } from 'graphql-hooks'

function MyComponent() {
  const client = useContext(ClientContext)
}

useQuery

Usage:

const state = useQuery(query, [options])

Example:

import { useQuery } from 'graphql-hooks'

function MyComponent() {
  const { loading, error, data } = useQuery(query)

  if (loading) return 'Loading...'
  if (error) return 'Something bad happened'

  return <div>{data.thing}</div>
}

This is a custom hook that takes care of fetching your query and storing the result in the cache. It won't refetch the query unless query or options.variables changes.

  • query: Your GraphQL query as a plain string
  • options: Object with the following optional properties
    • variables: Object e.g. { limit: 10 }
    • operationName: If your query has multiple operations, pass the name of the operation you wish to execute.
    • useCache: Boolean - defaults to true; cache the query result
    • skipCache: Boolean - defaults to false; If true it will by-pass the cache and fetch, but the result will then be cached for subsequent calls. Note the refetch function will do this automatically
    • ssr: Boolean - defaults to true. Set to false if you wish to skip this query during SSR
    • fetchOptionsOverrides: Object - Specific overrides for this query. See MDN for info on what options can be passed
    • updateData(previousData, data): Function - Custom handler for merging previous & new query results; return value will replace data in useQuery return value
      • previousData: Previous GraphQL query or updateData result
      • data: New GraphQL query result

useQuery return value

const { loading, error, data, refetch, cacheHit, ...errors } = useQuery(QUERY)
  • loading: Boolean - true if the query is in flight
  • error: Boolean - true if fetchError or httpError or graphQLErrors has been set
  • data: Object - the result of your GraphQL query
  • refetch(options): Function - useful when refetching the same query after a mutation; NOTE this presets skipCache=true & will bypass the options.updateData function that was passed into useQuery. You can pass a new updateData into refetch if necessary.
    • options: Object - options that will be merged into the options that were passed into useQuery (see above).
  • cacheHit: Boolean - true if the query result came from the cache, useful for debugging
  • fetchError: Object - Set if an error occurred during the fetch call
  • httpError: Object - Set if an error response was returned from the server
  • graphQLErrors: Array - Populated if any errors occurred whilst resolving the query

useManualQuery

Use this when you don't want a query to automatically be fetched, or wish to call a query programmatically.

Usage:

const [queryFn, state] = useManualQuery(query, [options])

Example:

import { useManualQuery } from 'graphql-hooks'

function MyComponent(props) {
  const [fetchUser, { loading, error, data }] = useManualQuery(GET_USER_QUERY, {
    variables: { id: props.userId }
  })

  return (
    <div>
      <button onClick={fetchUser}>Get User!</button>
      {error && <div>Failed to fetch user<div>}
      {loading && <div>Loading...</div>}
      {data && <div>Hello ${data.user.name}</div>}
    </div>
  )
}

If you don't know certain options when declaring the useManualQuery you can also pass the same options to the query function itself when calling it:

import { useManualQuery } from 'graphql-hooks'

function MyComponent(props) {
  const [fetchUser] = useManualQuery(GET_USER_QUERY)

  const fetchUserThenSomething = async () => {
    const user = await fetchUser({
      variables: { id: props.userId }
    })
    return somethingElse()
  }

  return (
    <div>
      <button onClick={fetchUserThenSomething}>Get User!</button>
    </div>
  )
}

useMutation

Mutations unlike Queries are not cached.

Usage:

const [mutationFn, state] = useMutation(mutation, [options])

Example:

import { useMutation } from 'graphql-hooks'

const UPDATE_USER_MUTATION = `mutation UpdateUser(id: String!, name: String!) {
  updateUser(id: $id, name: $name) {
    name
  }
}`

function MyComponent({ id, name }) {
  const [updateUser] = useMutation(UPDATE_USER_MUTATION)
  const [newName, setNewName] = useState(name)

  return (
    <div>
      <input
        type="text"
        value={newName}
        onChange={e => setNewName(e.target.value)}
      />
      <button
        onClick={() => updateUser({ variables: { id, name: newName } })}
      />
    </div>
  )
}

The options object that can be passed either to useMutation(mutation, options) or mutationFn(options) can be set with the following properties:

  • variables: Object e.g. { limit: 10 }
  • operationName: If your query has multiple operations, pass the name of the operation you wish to execute.
  • fetchOptionsOverrides: Object - Specific overrides for this query. See MDN for info on what options can be passed

Guides

SSR

See graphql-hooks-ssr for an in depth guide.

Pagination

GraphQL Pagination can be implemented in various ways and it's down to the consumer to decide how to deal with the resulting data from paginated queries. Take the following query as an example of offset pagination:

export const allPostsQuery = `
  query allPosts($first: Int!, $skip: Int!) {
    allPosts(first: $first, skip: $skip) {
      id
      title
      url
    }
    _allPostsMeta {
      count
    }
  }
`

In this query, the $first variable is used to limit the number of posts that are returned and the $skip variable is used to determine the offset at which to start. We can use these variables to break up large payloads into smaller chunks, or "pages". We could then choose to display these chunks as distinct pages to the user, or use an infinite loading approach and append each new chunk to the existing list of posts.

Separate pages

Here is an example where we display the paginated queries on separate pages:

import { React, useState } from 'react'
import { useQuery } from 'graphql-hooks'

export default function PostList() {
  // set a default offset of 0 to load the first page
  const [skipCount, setSkipCount] = useState(0)

  const { loading, error, data } = useQuery(allPostsQuery, {
    variables: { skip: skipCount, first: 10 }
  })

  if (error) return <div>There was an error!</div>
  if (loading && !data) return <div>Loading</div>

  const { allPosts, _allPostsMeta } = data
  const areMorePosts = allPosts.length < _allPostsMeta.count

  return (
    <section>
      <ul>
        {allPosts.map(post => (
          <li key={post.id}>
            <a href={post.url}>{post.title}</a>
          </li>
        ))}
      </ul>
      <button
        // reduce the offset by 10 to fetch the previous page
        onClick={() => setSkipCount(skipCount - 10)}
        disabled={skipCount === 0}
      >
        Previous page
      </button>
      <button
        // increase the offset by 10 to fetch the next page
        onClick={() => setSkipCount(skipCount + 10)}
        disabled={!areMorePosts}
      >
        Next page
      </button>
    </section>
  )
}

Infinite loading

Here is an example where we append each paginated query to the bottom of the current list:

import { React, useState } from 'react'
import { useQuery } from 'graphql-hooks'

// use options.updateData to append the new page of posts to our current list of posts
const updateData = (prevData, data) => ({
  ...data,
  allPosts: [...prevData.allPosts, ...data.allPosts]
})

export default function PostList() {
  const [skipCount, setSkipCount] = useState(0)

  const { loading, error, data } = useQuery(
    allPostsQuery,
    { variables: { skip: skipCount, first: 10 } },
    updateData
  )

  if (error) return <div>There was an error!</div>
  if (loading && !data) return <div>Loading</div>

  const { allPosts, _allPostsMeta } = data
  const areMorePosts = allPosts.length < _allPostsMeta.count

  return (
    <section>
      <ul>
        {allPosts.map(post => (
          <li key={post.id}>
            <a href={post.url}>{post.title}</a>
          </li>
        ))}
      </ul>
      {areMorePosts && (
        <button
          // set the offset to the current number of posts to fetch the next page
          onClick={() => setSkipCount(allPosts.length)}
        >
          Show more
        </button>
      )}
    </section>
  )
}

Authentication

Coming soon!

Fragments

Coming soon!

Migrating from Apollo

For a real life example, compare the next.js with-apollo vs with-graphql-hooks. We have feature parity and the main-*.js bundle is a whopping 93% smaller (7.9KB vs 116KB).

ApolloClient ➑️ GraphQLClient

- import { ApolloClient } from 'apollo-client'
- import { InMemoryCache } from 'apollo-cache-inmemory'
+ import { GraphQLClient } from 'graphql-hooks'
+ import memCache from 'graphql-hooks-memcache'

- const client = new ApolloClient({
-  uri: '/graphql',
-  cache: new InMemoryCache()
- })
+ const client = new GraphQLClient({
+   url: '/graphql',
+   cache: memCache()
+ })

A lot of the options you'd pass to ApolloClient are the same as GraphQLClient:

  • uri ➑️ url
  • fetchOptions
  • onError - the function signature is slightly different
  • headers
  • fetch
  • cache

ApolloProvider ➑️ ClientContext.Provider

- import { ApolloProvider } from 'react-apollo'
+ import { ClientContext } from 'graphql-hooks'

function App({ client }) {
  return (
-    <ApolloProvider client={client}>
+    <ClientContext.Provider value={client}>
       {/* children */}
+    </ClientContext.Provider>
-    </ApolloProvider>
  )
}

Query Component ➑️ useQuery

- import { Query } from 'react-apollo'
- import gql from 'graphql-tag'
+ import { useQuery } from 'graphql-hooks'

function MyComponent() {
+ const { loading, error, data } = useQuery('...')

-  return (
-    <Query query={gql`...`}>
-     {({ loading, error, data}) => {
        if (loading) return 'Loading...'
        if (error) return 'Error :('

        return <div>{data}</div>
-      }}
-    </Query>
-  )
}

Query Component Props

A lot of options can be carried over as-is, or have direct replacements:

  • query ➑️ useQuery(query): No need to wrap the query in gql
  • variables ➑️ useQuery(query, { variables })
  • ssr ➑️ useQuery(query, { ssr })
  • Fetch Policies: See #75 for more info
    • cache-first: This the default behaviour of graphql-hooks
    • cache-and-network: The refetch function provides this behaviour it will set loading: true, but the old data will be still set until the fetch resolves.
    • network-only ➑️ useQuery(QUERY, { skipCache: true })
    • cache-only: Not supported
    • no-cache ➑️ useQuery(QUERY, { useCache: false })

Not yet supported

  • errorPolicy: Any error will set the error to be truthy. See useQuery for more details.
  • pollInterval
  • notifyOnNetworkStatusChange
  • skip
  • onCompleted: Similar ability if using useManualQuery
  • onError: Similar ability if using useManualQuery
  • partialRefetch

Query Component Render Props

- <Query query={gql`...`}>
-  {(props) => {}}
- </Query>
+ const state = useQuery(`...`)
  • props.loading ➑️ const { loading } = useQuery('...')
  • props.error ➑️ const { error } = useQuery('...'): The error value from useQuery is Boolean the details of the error can be found in either:
    • state.fetchError
    • state.httpError
    • state.graphQLErrors
  • props.refetch ️➑️ const { refetch } = useQuery('...')
  • props.updateData(prevResult, options) ️➑️ state.updateData(prevResult, newResult)

Not yet supported

  • props.networkStatus
  • props.startPolling
  • props.stopPolling
  • props.subscribeToMore

Mutation Component ➑️ useMutation

- import { Mutation } from 'react-apollo'
- import gql from 'graphql-tag'
+ import { useMutation } from 'graphql-hooks'

function MyComponent() {
+ const [mutateFn, { loading, error, data }] = useMutation('...')

-  return (
-    <Mutation mutation={gql`...`}>
-     {(mutateFn, { loading, error }) => {
        if (error) return 'Error :('

        return <button disabled={loading} onClick={() => mutateFn()}>Submit</button>
-      }}
-    </Mutation>
-  )
}

Mutation Props

  • mutation ➑️ useMutation(mutation) - no need to wrap it in gql
  • variables ➑️️ useMutation(mutation, { variables }) or mutateFn({ variables })
  • ignoreResults ➑️️️️ const [mutateFn] = useMutation(mutation)
  • onCompleted ➑️ ️mutateFn().then(onCompleted)
  • onError ➑️ mutateFn().then(({ error }) => {...})

Not yet supported

  • update: Coming soon #52
  • optimisticResponse
  • refetchQueries
  • awaitRefetchQueries
  • context

Mutation Component Render Props

- <Mutation mutation={gql`...`}>
-  {(mutateFn, props) => {}}
- </Mutation>
+ const [mutateFn, state] = useMutation(`...`)
  • props.data ➑️ const [mutateFn, { data }] = useMutation()
  • props.loading ➑️ const [mutateFn, { loading }] = useMutation()
  • props.error ➑️ const [mutateFn, { error }] = useMutation(): The the details of the error can be found in either:
    • state.fetchError
    • state.httpError
    • state.graphQLErrors
  • client ️➑️️ const client = useContext(ClientContext) see ClientContext

Not yet supported

  • called

Contributors

Thanks goes to these wonderful people (emoji key):

Brian Mullan
Brian Mullan

πŸ’¬ πŸ› πŸ’» πŸ–‹ πŸ“– πŸ’‘ πŸ€” 🚧 πŸ‘€ ⚠️
Jack Clark
Jack Clark

πŸ’¬ πŸ› πŸ’» πŸ–‹ πŸ“– πŸ’‘ πŸ€” 🚧 πŸ‘€ ⚠️
Joe Warren
Joe Warren

πŸ’¬ πŸ› πŸ’» πŸ–‹ πŸ“– πŸ’‘ πŸ€” 🚧 πŸ‘€ ⚠️
Simone Busoli
Simone Busoli

πŸ’¬ πŸ› πŸ“–
jhey tompkins
jhey tompkins

⚠️ πŸ’¬ πŸ› πŸ’» πŸ–‹ πŸ‘€
Haroen Viaene
Haroen Viaene

πŸ›
Ari Bouius
Ari Bouius

πŸ“– πŸ› πŸ’» ⚠️
Klemen KogovΕ‘ek
Klemen KogovΕ‘ek

πŸ› πŸ€” πŸ’» ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

BrowserStack

We use BrowserStack to support as many browsers and devices as possible

You can’t perform that action at this time.