$ show nearform/graphql-hooks
graphql-hooks is a lightweight React GraphQL client library that provides a set of hooks for querying, mutating, and subscribing to GraphQL endpoints. It is designed as a minimal yet feature-rich alternative to Apollo Client, with a focus on small bundle size (22.9 kB gzipped). The library is organized as a Lerna monorepo containing the core package (`graphql-hooks`), an in-memory cache (`graphql-hooks-memcache`), SSR utilities (`graphql-hooks-ssr`), and a Babel plugin for compile-time GraphQL query extraction (`babel-plugin-extract-gql`). In production, the system operates as a client-side GraphQL executor within React applications. The primary entry points are React hooks: `useQuery`, `useMutation`, `useManualQuery`, and `useSubscription`. These hooks internally use `GraphQLClient` to send HTTP or WebSocket requests, passing through an optional middleware pipeline. The client supports caching via a pluggable interface (defaulting to `graphql-hooks-memcache` with LRU eviction and TTL), automatic refetching after mutations, file uploads via the GraphQL multipart spec, and server-side rendering by pre-fetching query results and injecting initial state into the HTML. Key data flows begin when a React component calls a hook. The hook interacts with `GraphQLClient`, which applies middleware (e.g., Automatic Persisted Queries or custom interceptors) before sending the request. Responses are cached and returned to the component. Mutations can optionally trigger refetches of related queries via an event emitter. The architecture promotes separation of concerns via middleware, a clean cache API, and support for multiple transport layers (HTTP, WebSocket, Full-WS). External dependencies include React (peer), `graphql-ws` or `subscriptions-transport-ws` for subscriptions, and `formdata-node` for file uploads in Node environments.
The LLM identified 3 files worth highlighting for reuse:
Implements Automatic Persisted Queries (APQ) as a middleware function. It intercepts outgoing GraphQL requests, sends a SHA-256 hash of the query first, and falls back to the full query only if the server returns a PersistedQueryNotFound error. This reduces network payload for repeated queries. The middleware follows a clean `(middleware) => next => ...` pattern that is self-contained and can be reused in any GraphQL client that supports middleware pipelines.
A pluggable in-memory cache implementing the required cache interface (`get`, `set`, `delete`, `clear`, `keys`, `getInitialState`). It uses an LRU eviction strategy with optional TTL per entry. The module is self-contained, exports a single class, and can be replaced by any cache implementation (e.g., Redis, localStorage) that adheres to the interface. This pattern is reusable across projects needing a lightweight client-side cache.
A custom React hook that provides a stable callback reference based on deep equality of dependencies, rather than reference equality. It leverages the `use-deep-compare-effect` library to avoid unnecessary re-renders when dependencies are objects or arrays. This hook is self-contained, has no internal project dependencies beyond React and a small utility, and can be extracted into any React project to prevent callback instability caused by object/array identity changes.