A highly customisable and versatile GraphQL client

✨ Features

• 📦 One package to get a working GraphQL client in React, Preact, Vue, Solid and Svelte
• ⚙️ Fully customisable behaviour via "exchanges"
• 🗂 Logical but simple default behaviour and document caching
• 🌱 Normalized caching via @urql/exchange-graphcache
• 🔬 Easy debugging with the urql devtools browser extensions

urql is a GraphQL client that exposes a set of helpers for several frameworks. It's built to be highly customisable and versatile so you can take it from getting started with your first GraphQL project all the way to building complex apps and experimenting with GraphQL clients.

📃 For more information, check out the docs.

💙 Sponsors

BigCommerce

WunderGraph

The Guild

BeatGig

🙌 Contributing

The urql project was founded by Formidable and is actively developed by the urql GraphQL team.

If you'd like to get involved, check out our Contributor's guide.

📦 Releases

All new releases and updates are listed on GitHub with full changelogs. Each package in this repository further contains an independent CHANGELOG.md file with the historical changelog, for instance, here’s @urql/core’s changelog.

If you’re upgrading to v4, check out our migration guide, posted as an issue.

New releases are prepared using changesets, which are changelog entries added to each PR, and we have “Version Packages” PRs that once merged will release new versions of urql packages. You can use @canary releases from npm if you’d like to get a preview of the merged changes.

📃 Documentation

The documentation contains everything you need to know about urql, and contains several sections in order of importance when you first get started:

• Basics — contains the "Getting Started" guide and all you need to know when first using urql.
• Architecture — explains how urql functions and is built.
• Advanced — covers more uncommon use-cases and things you don't immediately need when getting started.
• Graphcache — documents "Normalized Caching" support which enables more complex apps and use-cases.
• API — the API documentation for each individual package.

Furthermore, all APIs and packages are self-documented using TSDocs. If you’re using a language server for TypeScript, the documentation for each API should pop up in your editor when hovering urql’s code and APIs.

You can find the raw markdown files inside this repository's docs folder.

Changelog

2.3.1

Patch Changes

• Omit minified files and sourcemaps' sourcesContent in published packages Submitted by @kitten (See #3755)
• Updated dependencies (See #3755)
  • @urql/core@5.1.1

2.3.0

Minor Changes

• Mark @urql/core as a peer dependency as well as a regular dependency Submitted by @kitten (See #3579)

2.2.2

Patch Changes

• Update build process to generate correct source maps Submitted by @kitten (See #3201)

2.2.1

Patch Changes

• Publish with npm provenance Submitted by @kitten (See #3180)

2.2.0

Minor Changes

• Update exchanges to drop redundant share calls, since @urql/core’s composeExchanges utility now automatically does so for us Submitted by @kitten (See #3082)
• Remove getOperationName export from @urql/core Submitted by @kitten (See #3062)

Patch Changes

• Upgrade to wonka@^6.3.0 Submitted by @kitten (See #3104)
• Add TSDocs for all exchanges, documenting API internals Submitted by @kitten (See #3072)
• Updated dependencies (See #3101, #3033, #3054, #3053, #3060, #3081, #3039, #3104, #3082, #3097, #3061, #3055, #3085, #3079, #3087, #3059, #3055, #3057, #3050, #3062, #3051, #3043, #3063, #3054, #3102, #3097, #3106, #3058, and #3062)
  • @urql/core@4.0.0

2.1.1

Patch Changes

• ⚠️ Fix type-generation, with a change in TS/Rollup the type generation took the paths as src and resolved them into the types dir, by @JoviDeCroock (See #2870)
• Updated dependencies (See #2872, #2870, and #2871)
  • @urql/core@3.1.1

2.1.0

Minor Changes

• The context option, which may be set to a context value or a function returning a context, can now return a Promise and will be correctly resolved and awaited, by @YutaUra (See #2806)

Patch Changes

• End iterator when teardown functions runs, previously it waited for one extra call to next, then ended the iterator, by @danielkaxis (See #2803)
• Updated dependencies (See #2843, #2847, #2850, and #2846)
  • @urql/core@3.1.0

2.0.0

Major Changes

• Goodbye IE11! 👋 This major release removes support for IE11. All code that is shipped will be transpiled much less and will not be ES5-compatible anymore, by @kitten (See #2504)
• Upgrade to Wonka v6 (wonka@^6.0.0), which has no breaking changes but is built to target ES2015 and comes with other minor improvements. The library has fully been migrated to TypeScript which will hopefully help with making contributions easier!, by @kitten (See #2504)

Minor Changes

• Remove the babel-plugin-modular-graphql helper, this because the graphql package hasn't converted to ESM yet which gives issues in node environments, by @JoviDeCroock (See #2551)

Patch Changes

• ⚠️ fix return for context function argument, by @JoviDeCroock (See #2583)
• Updated dependencies (See #2551, #2504, #2619, #2607, and #2504)
  • @urql/core@3.0.0

1.2.3

Patch Changes

• Support using default values with directives. Previously, using a variables with a default value within a directive would fail the validation if it is empty, by @fathyb (See #2435)

1.2.2

Patch Changes

• Upgrade modular imports for graphql package, which fixes an issue in @urql/exchange-execute, where graphql@16 files wouldn't resolve the old subscribe import from the correct file, by @kitten (See #2149)

1.2.1

Patch Changes

• Extend peer dependency range of graphql to include ^16.0.0. As always when upgrading across many packages of urql, especially including @urql/core we recommend you to deduplicate dependencies after upgrading, using npm dedupe or npx yarn-deduplicate, by @kitten (See #2133)
• Updated dependencies (See #2133)
  • @urql/core@2.3.6

1.2.0

Minor Changes

• Add subscription support, by @Tigge (See #2061)

Patch Changes

• Updated dependencies (See #2074)
  • @urql/core@2.3.5

1.1.0

Minor Changes

• Support async iterated results, including subscriptions via AsyncIterator support and @defer / @stream if the appropriate version of graphql is used, e.g. 15.4.0-experimental-stream-defer.1, by @kitten (See #1854)

Patch Changes

• Updated dependencies (See #1854)
  • @urql/core@2.3.0

1.0.5

Patch Changes

• Expose ExecuteExchangeArgs interface, by @taneba (See #1837)
• Updated dependencies (See #1829)
  • @urql/core@2.1.6

1.0.4

Patch Changes

• Remove closure-compiler from the build step (See #1570)
• Updated dependencies (See #1570, #1509, #1600, and #1515)
  • @urql/core@2.1.0

1.0.3

Patch Changes

• Export getOperationName from @urql/core and use it in @urql/exchange-execute, fixing several imports, by @JoviDeCroock (See #1135)
• Updated dependencies (See #1135)
  • @urql/core@1.15.1

1.0.2

Patch Changes

• Add missing .mjs extension to all imports from graphql to fix Webpack 5 builds, which require extension-specific import paths for ESM bundles and packages. This change allows you to safely upgrade to Webpack 5., by @kitten (See #1094)
• Deprecate the Operation.operationName property in favor of Operation.kind. This name was previously confusing as operationName was effectively referring to two different things. You can safely upgrade to this new version, however to mute all deprecation warnings you will have to upgrade all urql packages you use. If you have custom exchanges that spread operations, please use the new makeOperation helper function instead, by @bkonkle (See #1045)
• Updated dependencies (See #1094 and #1045)
  • @urql/core@1.14.0

1.0.1

Patch Changes

• Upgrade to a minimum version of wonka@^4.0.14 to work around issues with React Native's minification builds, which use uglify-es and could lead to broken bundles, by @kitten (See #842)
• Updated dependencies (See #838 and #842)
  • @urql/core@1.12.0

v1.0.0

Initial Release