Registry / api / graphql-hooks

graphql-hooks

library8.2.0jsnpmunverified

Minimal, hooks-based GraphQL client for React (v8.2.0, stable, maintained). Provides `useQuery`, `useMutation`, and `GraphQLProvider` with zero extra dependencies beyond React 17/18/19. Smaller bundle than Apollo Client (~3KB gzipped vs 30KB+), no cache or schema introspection by default. Ideal for lightweight React applications. Ships TypeScript definitions. Released under MIT. Current cadence: minor releases every few months.

api

npm install graphql-hooks

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-HOOKS

graphql-hooks

apijavascriptv8.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GraphQLProvider

✓ import { GraphQLProvider } from 'graphql-hooks'

✗ const { GraphQLProvider } = require('graphql-hooks')

ESM-only; CJS require() will fail in Node. Use ESM imports.

useQuery

✓ import { useQuery } from 'graphql-hooks'

✗ import useQuery from 'graphql-hooks'

Named export, not default. TypeScript supports auto-import.

useMutation

✓ import { useMutation } from 'graphql-hooks'

✗ import { useMutation } from 'graphql-hooks/useMutation'

All hooks are top-level exports from 'graphql-hooks'.

Sets up GraphQLProvider with a client, then uses useQuery to fetch posts.

import React from 'react'; import { GraphQLProvider, useQuery, useMutation } from 'graphql-hooks'; const client = new GraphQLClient({ url: process.env.GRAPHQL_URL ?? 'https://example.com/graphql' }); function Posts() { const { loading, error, data } = useQuery(` query Posts { posts { id title } } `); if (loading) return <p>Loading...</p>; if (error) return <p>Error: {error.message}</p>; return ( <ul> {data.posts.map(post => ( <li key={post.id}>{post.title}</li> ))} </ul> ); } function App() { return ( <GraphQLProvider client={client}> <Posts /> </GraphQLProvider> ); } export default App;

Debug

Known issues

breakingIn v6, the default cache is removed; you must provide a cache implementation or use the new minimal mode.

fix

If you relied on default caching, switch to graphql-hooks-memcache or implement custom cache.

affects: >=6.0.0 <7.0.0

breakingIn v8, the client constructor no longer accepts headers as second parameter; use options object.

fix

new GraphQLClient({ url, headers: { ... } }) instead of new GraphQLClient(url, headers).

affects: >=8.0.0

deprecatedThe `logErrors` option is deprecated and will be removed in v9. Use `onError` callback instead.

fix

Use onError: (err, query, variables) => console.error(err) instead.

affects: >=7.0.0 <9.0.0

gotchauseQuery does not refetch on component remount unless you change the key option.

fix

Force refetch by providing a key prop that changes when you want to refetch, or call refetch from the returned object.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot destructure property 'data' of 'undefined'

Missing GraphQLProvider wrapping a component that uses useQuery.

fix

Wrap the component tree with <GraphQLProvider client={client}>.

Error: 'graphql-hooks' is not defined

Using CommonJS require() in an ESM-only package.

fix

Use ES6 import syntax: import { GraphQLClient } from 'graphql-hooks'.

Invariant Violation: Must have a GraphQL client. Wrap your component in a <GraphQLProvider>.

useQuery or useMutation used outside of provider context.

fix

Ensure all components using hooks are children of <GraphQLProvider>.

Upgrade

Version history

8.2.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency: required at runtime for hooks and context.

Agent activity

41 hits · last 30 days

node

OpenAI (training)

Resources

githubgit://github.com/nearform/graphql-hooks ↗

packagegraphql-hooks ↗

homepagehttps://github.com/nearform/graphql-hooks#readme ↗