{"id":15891,"library":"urql","title":"urql GraphQL Client for React","description":"urql is a lightweight and highly customizable GraphQL client primarily designed for React applications, though it offers integrations for other frameworks like Vue and Svelte via separate packages. It is currently at version 5.0.2 and maintains an active development cycle with frequent patch and minor releases across its extensive ecosystem of exchanges and framework integrations. Its core differentiator is a pluggable 'exchanges' architecture, which allows developers to swap out or add functionalities like caching, authentication, request batching, and subscriptions, making it incredibly adaptable to various application requirements. Unlike some other clients, urql's core remains minimal, pushing advanced features into these composable exchanges, providing fine-grained control and reducing bundle size when not all features are needed. It ships with full TypeScript support.","status":"active","version":"5.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/urql-graphql/urql","tags":["javascript","graphql client","state management","cache","graphql","exchanges","react","typescript"],"install":[{"cmd":"npm install urql","lang":"bash","label":"npm"},{"cmd":"yarn add urql","lang":"bash","label":"yarn"},{"cmd":"pnpm add urql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core GraphQL client logic and client instance (Client).","package":"@urql/core","optional":false},{"reason":"Required for the React-specific hooks and Provider component.","package":"react","optional":false}],"imports":[{"note":"The `Provider` context component is essential for making the urql client available to child components. Use named import.","wrong":"const { Provider } = require('urql')","symbol":"Provider","correct":"import { Provider } from 'urql'"},{"note":"This is the primary hook for executing GraphQL queries in React components. It's a named export.","wrong":"import urql from 'urql'; urql.useQuery()","symbol":"useQuery","correct":"import { useQuery } from 'urql'"},{"note":"`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.","wrong":"import { Client } from 'urql'; new Client({})","symbol":"Client configuration","correct":"import { createClient, cacheExchange, fetchExchange } from 'urql'"}],"quickstart":{"code":"import React from 'react';\nimport { createRoot } from 'react-dom/client';\nimport { createClient, Provider, cacheExchange, fetchExchange, useQuery } from 'urql';\n\n// 1. Create your urql client\nconst client = createClient({\n url: 'https://swapi-graphql.netlify.app/.netlify/functions/index', // Example public GraphQL API\n exchanges: [cacheExchange, fetchExchange], // Define the exchanges to use (e.g., caching, fetching)\n});\n\n// 2. Define a React component that uses the useQuery hook\nconst StarWarsFilms = () => {\n const [result] = useQuery({\n query: `\n query AllFilms {\n allFilms {\n films {\n title\n director\n releaseDate\n }\n }\n }\n `,\n });\n\n const { data, fetching, error } = result;\n\n if (fetching) return

Loading films...

;\n if (error) return

Oh no... {error.message}

;\n\n return (\n
\n

Star Wars Films

\n \n
\n );\n};\n\n// 3. Wrap your root component with the Provider\nconst App = () => (\n \n \n \n);\n\n// 4. Render your application\nconst container = document.getElementById('root');\nif (container) {\n const root = createRoot(container);\n root.render();\n} else {\n console.error(\"Root element not found\");\n}\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=@urql/exchange-graphcache@9.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=3.x of @urql/core and related packages, including urql"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `import { createClient } from 'urql'; const client = createClient({...});` instead of `import { Client } from 'urql'; const client = new Client({...});`","message":"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.","severity":"deprecated","affected_versions":"All versions, but more pronounced in newer ones."}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Wrap your root React component (or the relevant part of your application) with `...`, where `client` is your initialized `urql` client instance.","cause":"The `urql` client instance was not provided to your React component tree via the `` component, or the component trying to use a hook (like `useQuery`) is outside the `Provider`'s scope.","error":"Client is not provided. Please make sure to add a `Provider`."},{"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.","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.","error":"TypeError: (0 , urql__WEBPACK_IMPORTED_MODULE_2__.useQuery) is not a function"},{"fix":"When rendering data from `useQuery`, iterate over arrays and access specific scalar properties. For example, instead of `
{data.allFilms.films}
`, use ``.","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).","error":"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."}],"ecosystem":"npm"}