Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Provider
✓ import { Provider } from 'urql'
✗ const { Provider } = require('urql')
The `Provider` context component is essential for making the urql client available to child components. Use named import.
useQuery
✓ import { useQuery } from 'urql'
✗ import urql from 'urql'; urql.useQuery()
This is the primary hook for executing GraphQL queries in React components. It's a named export.
Client configuration
✓ import { createClient, cacheExchange, fetchExchange } from 'urql'
✗ import { Client } from 'urql'; new Client({})
`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.
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");
}
Debug
Known issues
breakingThe `@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.fixUsers 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.
affects: >=@urql/exchange-graphcache@9.0.0
gotchaurql 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.fixAlways 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`. affects: >=3.x of @urql/core and related packages, including urql
gotchaIncorrect 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.fixAlways 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`).
affects: All versions
deprecatedDirectly 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.fixUse `import { createClient } from 'urql'; const client = createClient({...});` instead of `import { Client } from 'urql'; const client = new Client({...});` affects: All versions, but more pronounced in newer ones.
Errors
Common errors & fixes
Client is not provided. Please make sure to add a `Provider`.
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.
fixWrap 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
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.
fixEnsure 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.
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).
fixWhen 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>`. Audit
Dependencies
@urql/corerequiredProvides the core GraphQL client logic and client instance (Client).
reactrequiredRequired for the React-specific hooks and Provider component.