urql GraphQL Client for React

Common errors

• Client is not provided. Please make sure to add a `Provider`.

  cause The `urql` client instance was not provided to your React component tree via the `<Provider>` component, or the component trying to use a hook (like `useQuery`) is outside the `Provider`'s scope.
  fix Wrap your root React component (or the relevant part of your application) with `<Provider value={client}>...</Provider>`, where `client` is your initialized `urql` client instance.

• TypeError: (0 , urql__WEBPACK_IMPORTED_MODULE_2__.useQuery) is not a function

  cause This typically indicates that `useQuery` was imported incorrectly, often due to trying to use `require()` syntax in a CommonJS context when the library expects ESM, or a bundler misconfiguration.
  fix Ensure you are using ES module imports: `import { useQuery } from 'urql'`. Verify your `tsconfig.json` (if TypeScript) and bundler configuration (`webpack.config.js`, `vite.config.ts`) are set up for ESM.

• Error: Objects are not valid as a React child (found: object with keys {__typename, id, title}). If you meant to render a collection of children, use an array instead.

  cause You are attempting to render a raw GraphQL data object directly within JSX without mapping or transforming it into valid React elements (e.g., strings, numbers, or React components).
  fix When rendering data from `useQuery`, iterate over arrays and access specific scalar properties. For example, instead of `<div>{data.allFilms.films}</div>`, use `<ul>{data.allFilms.films.map(film => <li key={film.title}>{film.title}</li>)}</ul>`.

Warnings

• breaking The `@urql/exchange-graphcache` package, often used with `urql` for normalized caching, introduced a major breaking change in version 9.0.0. It no longer serializes data to IndexedDB. This change invalidates all existing cached data and significantly impacts applications relying on persisted offline state through `graphcache`. While improving performance, it requires re-evaluating persistence strategies.
  Fix: Users migrating to `graphcache` v9.0.0 should be aware that all previously persisted data will be lost. Consider alternative storage solutions for persistence if required, or update your application logic to handle initial cache misses. Consult the `graphcache` documentation for migration guidance.
• gotcha urql and its core packages are primarily developed for ESM (ECMAScript Modules). While CJS (CommonJS) compatibility exists for older Node.js versions, using `require()` syntax with newer `urql` versions or in an ESM-first project can lead to module resolution errors or unexpected behavior.
  Fix: Always use ES module `import` syntax (`import { ... } from 'urql'`) in your projects. Ensure your build tooling (Webpack, Rollup, Vite) and Node.js environment are configured to handle ESM correctly, potentially by setting `"type": "module"` in your `package.json`.
• gotcha Incorrect or mismatched versions of `@urql/core` peer dependency with the `urql` package can lead to runtime errors, unexpected behavior, or type conflicts, especially during major version updates.
  Fix: Always ensure that your installed `@urql/core` version matches the peer dependency requirement of your `urql` package. Use `npm install` or `yarn install` to resolve peer dependencies automatically, or explicitly install the correct version (e.g., `npm install urql @urql/core@^6.0.0`).
• deprecated Directly importing `Client` and instantiating it with `new Client({...})` is technically possible but `createClient` is the recommended approach for initializing your urql client instance. This function handles default setups and is often more future-proof.
  Fix: Use `import { createClient } from 'urql'; const client = createClient({...});` instead of `import { Client } from 'urql'; const client = new Client({...});`

Install

• npm install urql npm
• yarn add urql yarn
• pnpm add urql pnpm

Imports

• Provider
  wrong:

  const { Provider } = require('urql')

  correct:

  import { Provider } from 'urql'

  The `Provider` context component is essential for making the urql client available to child components. Use named import.
• useQuery
  wrong:

  import urql from 'urql'; urql.useQuery()

  correct:

  import { useQuery } from 'urql'

  This is the primary hook for executing GraphQL queries in React components. It's a named export.
• Client configuration
  wrong:

  import { Client } from 'urql'; new Client({})

  correct:

  import { createClient, cacheExchange, fetchExchange } from 'urql'

  `createClient` is the recommended factory function. `cacheExchange` and `fetchExchange` are common default exchanges for caching and network requests, respectively, often used in the client setup.

Quickstart

This snippet demonstrates how to set up `urql` with a React application, create a GraphQL client with essential exchanges (`cacheExchange`, `fetchExchange`), and fetch data using the `useQuery` hook, then render the results within a component.

import React from 'react';
import { createRoot } from 'react-dom/client';
import { createClient, Provider, cacheExchange, fetchExchange, useQuery } from 'urql';

// 1. Create your urql client
const client = createClient({
  url: 'https://swapi-graphql.netlify.app/.netlify/functions/index', // Example public GraphQL API
  exchanges: [cacheExchange, fetchExchange], // Define the exchanges to use (e.g., caching, fetching)
});

// 2. Define a React component that uses the useQuery hook
const StarWarsFilms = () => {
  const [result] = useQuery({
    query: `
      query AllFilms {
        allFilms {
          films {
            title
            director
            releaseDate
          }
        }
      }
    `,
  });

  const { data, fetching, error } = result;

  if (fetching) return <p>Loading films...</p>;
  if (error) return <p>Oh no... {error.message}</p>;

  return (
    <div>
      <h1>Star Wars Films</h1>
      <ul>
        {data.allFilms.films.map((film) => (
          <li key={film.title}>
            <strong>{film.title}</strong> by {film.director} (Released: {film.releaseDate})
          </li>
        ))}
      </ul>
    </div>
  );
};

// 3. Wrap your root component with the Provider
const App = () => (
  <Provider value={client}>
    <StarWarsFilms />
  </Provider>
);

// 4. Render your application
const container = document.getElementById('root');
if (container) {
  const root = createRoot(container);
  root.render(<App />);
} else {
  console.error("Root element not found");
}