NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm, #3808 most downloaded on npm
The shared core for the highly customizable and versatile GraphQL client
Latest stable
6.0.3
Last release 4 months ago
22 Jun 2026
Release timing varies
gaps range from 2 weeks to 10 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
283 releases · first in 2020
Drag across the ruler to compare, or tap a release to open it.
Allow providing a custom isSubscriptionOperation implementation, by @n1ru4l (See #2534)
Add Accept header to GraphQL HTTP requests. This complies to the specification but doesn't go as far as sending Content-Type which would throw a lot o
Accept header to GraphQL HTTP requests. This complies to the specification but doesn't go as far as sending Content-Type which would throw a lot of APIs off. Instead, we'll now be sending an accept header for application/graphql+json, application/json to indicate that we comply with the GraphQL over HTTP protocol.
This also fixes headers merging to allow overriding Accept and Content-Type regardless of the user options' casing, by @kitten (See #2457)withPromise cases, by @JoviDeCroock (See #2446)text/* as error messages, by @kitten (See #2456)Your coding agent can read these notes before it upgrades. Set up the MCP server →
cut off url when using the GET method at 2048 characters (lowest url-size coming from chromium), by @JoviDeCroock (See #2384)
url when using the GET method at 2048 characters (lowest url-size coming from chromium), by @JoviDeCroock (See #2384)toPromise() return would not result in the stream tearing down, by @JoviDeCroock (See #2386)Prevent ignored characters in GraphQL queries from being replaced inside strings and block strings. Previously we accepted sanitizing strings via regu
Undo logic to catch errors from incremental fetching and forking the response stream, introduce logic to detect results, by @JoviDeCroock (See #2287)
⚠️ Fix mutation operation being used as compared identity and instead add a stand-in comparison, by @kitten (See #2228)
Allow for repeated mutations that have similar inputs which results in the same key, this is for instance the case with file uploads, by @JoviDeCroock
@graphql-typed-document-node/core to 3.1.1 for graphql@16 support, by @JoviDeCroock (See #2153)network-only requests from the ssrExchange, this is to enable staleWhileRevalidated queries to successfully dispatch their queries, by @JoviDeCroock (See #2198)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
⚠️ Fix issue where maskTypename would ignore array shapes, by @JoviDeCroock (See #2074)
maskTypename would ignore array shapes, by @JoviDeCroock (See #2074)Prevent Buffer from being polyfilled by an automatic detection in Webpack. Instead of referencing the Buffer global we now simply check the constructo
Buffer from being polyfilled by an automatic detection in Webpack. Instead of referencing the Buffer global we now simply check the constructor name, by @kitten (See #2027)ExecutionResult to line up with subscription-libs, by @JoviDeCroock (See #1998)Adding option to ssrExchange to include the extensions field of operation results in the cache, by @dios-david (See #1985)
ssrExchange to include the extensions field of operation results in the cache, by @dios-david (See #1985)⚠️ Fix issue where the ssr-exchange would loop due to checking network-only revalidations, by @JoviDeCroock (See #1944)
Omit minified files and sourcemaps' sourcesContent in published packages Submitted by @kitten (See #3755)
query.__key as non-enumerable so formatDocument does not restore previous invocations when cloning the gql-ast, by @JoviDeCroock (See #1870)hasNext results. This change ensures that
when we call toPromise() on a query we wont serve an incomplete result, the
user will expect to receive a non-stale full-result when using toPromise(), by @JoviDeCroock (See #1880)Mark @urql/core as a peer dependency as well as a regular dependency Submitted by @kitten (See #3579)
@defer and @stream responses for GraphQL. This implements the "GraphQL Defer and Stream Directives" and "Incremental Delivery over HTTP" specifications. If a GraphQL API supports multipart/mixed responses for deferred and streamed delivery of GraphQL results, @urql/core (and all its derived fetch implementations) will attempt to stream results. This is only supported on browsers supporting streamed fetch responses, which excludes IE11.
The implementation of streamed multipart responses is derived from meros by @maraisr, and is subject to change if the RFCs end up changing, by @kitten (See #1854)Nothing published for this version
Mark @urql/core as a peer dependency as well as a regular dependency Submitted by @kitten (See #3579)
share calls, since @urql/core’s composeExchanges utility now automatically does so for us
Submitted by @kitten (See #3082)getOperationName export from @urql/core
Submitted by @kitten (See #3062)wonka@^6.3.0
Submitted by @kitten (See #3104)staleWhileRevalidate option to the ssrExchange, which allows the client to immediately refetch a new result on hydration, which may be used for cached / stale SSR or SSG pages. This is different from using cache-and-network by default (which isn't recommended) as the ssrExchange typically acts like a "replacement fetch request", by @kitten (See #1852)GET method, by @JoviDeCroock (See #1851)authExchange() will now block and pass on errors if the initialization function passed to it fails, and will retry indefinitely. It’ll also output a w
authExchange() will now block and pass on errors if the initialization function passed to it fails, and will retry indefinitely. It’ll also output a warning for these cases, as the initialization function (i.e. authExchange(async (utils) => { /*...*/ })) is not expected to reject/throw
Submitted by @kitten (See #3343)Handle refreshAuth rejections and pass the resulting error on to OperationResults on the authentication queue Submitted by @kitten (See #3307)
ssrExchange().restoreData() from adding results to the exchange that have already been invalidated. This may happen when restoreData() is called repeatedly, e.g. per page. When a prior run has already invalidated an SSR result then the result is 'migrated' to the user's cacheExchange, which means that restoreData() should never attempt to re-add it again, by @kitten (See #1776)stale: true, where a cache-first operation issued by Graphcache wouldn't yield an affected query and update its result to reflect the loading state with stale: true. This is a regression from v2.1.0 and mostly becomes unexpected when cache.invalidate(...) is used, by @kitten (See #1755)⚠️ Fix regression that caused teardowns to be ignored by an authExchange’s retry queue Submitted by @kitten (See #3235)
Update build process to generate correct source maps Submitted by @kitten (See #3201)
Publish with npm provenance Submitted by @kitten (See #3180)
⚠️ Fix operations created by utilities.mutate() erroneously being retried and sent again like a regular operation Submitted by @JoviDeCroock (See #316
utilities.mutate() erroneously being retried and sent again like a regular operation
Submitted by @JoviDeCroock (See #3164)useQuery from re-executing (and hitting the network) during SSR hydration when it's awaited for Suspense. Awaiting the query subscribed to the operation a second time, which re-dispatched it after the ssrExchange result had already been consumed, triggering a redundant network request even with staleWhileRevalidate: false. The awaited promise now resolves with the already-settled result instead of re-subscribing
Submitted by @JoviDeCroock (See #3884)await useQuery() in Vue to wait on the composable's existing reactive state instead of creating an additional query source subscription
Submitted by @JoviDeCroock (See #3890)Optional custom injection key support for provideClient, install, useClient, and useClientHandle. Multiple clients can be provided and consumed under
provideClient, install, useClient, and useClientHandle. Multiple clients can be provided and consumed under different keys; default key remains '$urql' for backward compatibility
Submitted by @albertcito (See #3858)minimumTime to refocusExchange to throttle query reexecution
Submitted by @ThaUnknown (See #3825)share calls, since @urql/core’s composeExchanges utility now automatically does so for us
Submitted by @kitten (See #3082)sourcesContent, including additional source files, and had incorrect paths in some of them
Submitted by @kitten (See #3053)wonka@^6.3.0
Submitted by @kitten (See #3104)didAuthError keeps returning true
Submitted by @JoviDeCroock (See #3112)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)Client will now also avoid executing an operation if it's already active, has a previous result available, and is either run with the cache-first or cache-only request policies. This is similar to a "short circuiting" behavior, where unnecessary work is avoided by not issuing more operations into the exchange pipeline than expected, by @kitten (See #1600)Client more forgiving when duplicate
sources are used, which previously made it difficult to use the same operation across an app
together with cache-and-network; This was a rare use-case, and it isn't recommended to overfetch
data across an app, however, the new Client implementation of shared sources ensures that when an
operation is active that the Client distributes the last known result for the active operation to
any new usages of it (which is called “replaying stale results”) (See #1515)Implement new authExchange API, which removes the need for an authState (i.e. an internal authentication state) and removes getAuth, replacing it with
authExchange API, which removes the need for an authState (i.e. an internal authentication state) and removes getAuth, replacing it with a separate refreshAuth flow.
The new API requires you to now pass an initializer function. This function receives a utils
object with utils.mutate and utils.appendHeaders utility methods.
It must return the configuration object, wrapped in a promise, and this configuration is similar to
what we had before, if you're migrating to this. Its refreshAuth method is now only called after
authentication errors occur and not on initialization. Instead, it's now recommended that you write
your initialization logic in-line.authExchange(async utils => {
let token = localStorage.getItem('token');
let refreshToken = localStorage.getItem('refreshToken');
return {
addAuthToOperation(operation) {
return utils.appendHeaders(operation, {
Authorization: `Bearer ${token}`,
});
},
didAuthError(error) {
return error.graphQLErrors.some(
e => e.extensions?.code === 'FORBIDDEN'
);
},
async refreshAuth() {
const result = await utils.mutate(REFRESH, { token });
if (result.data?.refreshLogin) {
token = result.data.refreshLogin.token;
refreshToken = result.data.refreshLogin.refreshToken;
localStorage.setItem('token', token);
localStorage.setItem('refreshToken', refreshToken);
}
},
};
});
Submitted by @kitten (See #3012)willAuthError not being called for operations that are waiting on the authentication state to update. This can actually lead to a common issue where operations that came in during the authentication initialization (on startup) will never have willAuthError called on them. This can cause an easy mistake where the initial authentication state is never checked to be valid
Submitted by @kitten (See #3017)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)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)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)pollInterval feature from OperationContext. Instead consider using a source that uses Wonka.interval and Wonka.switchMap over client.query()'s source, by @kitten (See #1374)operationName property from Operations. The new Operation.kind property is now preferred. If you're creating new operations you may also use the makeOperation utility instead.
When upgrading @urql/core please ensure that your package manager didn't install any duplicates of it. You may deduplicate it manually using npx yarn-deduplicate (for Yarn) or npm dedupe (for npm), by @kitten (See #1357)Add a workaround for graphql-tag/loader, which provides filtered query documents (where the original document contains multiple operations) without up
Add fragment deduplication to gql tag. Identical fragments can now be interpolated multiple times without a warning being triggered or them being dupl
Add a built-in gql tag function helper to @urql/core. This behaves similarly to graphql-tag but only warns about _locally_ duplicated fragment names r
Don't add undefined to any property of the ssrExchange's serialized results, as this would crash in Next.js, by @JoviDeCroock (See #1168)
undefined to any property of the ssrExchange's serialized results, as this would crash in Next.js, by @JoviDeCroock (See #1168)Export getOperationName from @urql/core and use it in @urql/exchange-execute, fixing several imports, by @JoviDeCroock (See #1135)
getOperationName from @urql/core and use it in @urql/exchange-execute, fixing several imports, by @JoviDeCroock (See #1135)It has now been ensured that client-side suspense functions without the deprecated suspenseExchange and uncached results are loaded consistently. As p…
suspenseExchange and uncached results are loaded consistently. As part of this work, the Client itself does now never throw Suspense promises anymore, which is functionality that either way has no place outside of the React/Preact bindings, by @kitten (See #1123)Record over object type for subscription operation variables. The object type is currently hard to use (see this issue), by @enisdenjo (See #1119)TypedDocumentNode to infer the type of the OperationResult and Operation for all methods, functions, and hooks that either directly or indirectly accept a DocumentNode. See graphql-typed-document-node and the corresponding blog post for more information., by @kitten (See #1113)useSource hooks which powers useQuery and useSubscription to improve various edge case behaviour. This will not change the behaviour of these hooks dramatically but avoid unnecessary state updates when any updates are obviously equivalent and the hook will furthermore improve continuation from mount to effects, which will fix cases where the state between the mounting and effect phase may slightly change, by @kitten (See #1104)⚠️ Fix the production build overwriting the development build. Specifically in the previous release we mistakenly replaced all development bundles wit
This version of @urql/core renames Operation.operationName to Operation.kind. For now the old property is merely deprecated and will issue a warning i…
This version of @urql/core renames Operation.operationName to Operation.kind. For now the old
property is merely deprecated and will issue a warning if it's used directly. That said, all
exchanges that are released today also need this new version of @urql/core@>=1.14.0, so if you
upgrade to any of the following packages, you will also need to upgrade @urql/core. If you upgrade
and see the deprecation warning, check whether all following exchanges have been upgraded:
@urql/exchange-auth@0.1.2@urql/exchange-execute@1.0.2@urql/exchange-graphcache@3.1.8@urql/exchange-multipart-fetch@0.1.10@urql/exchange-persisted-fetch@1.2.2@urql/exchange-populate@0.2.1@urql/exchange-refocus@0.2.1@urql/exchange-retry@0.1.9@urql/exchange-suspense@1.9.2Once you've upgraded @urql/core please also ensure that your package manager hasn't accidentally
duplicated the @urql/core package. If you're using npm you can do so by running npm dedupe,
and if you use yarn you can do so by running yarn-deduplicate.
If you have a custom exchange, you can mute the deprecation warning by using Operation.kind rather
than Operation.operationName. If these exchanges are copying or altering operations by spreading
them this will also trigger the warning, which you can fix by using the new makeOperation helper
function.
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)Allow client.reexecuteOperation to be called with mutations which skip the active operation minimums, by @kitten (See #1011)
Please note that this release changes the data structure of the ssrExchange's output. We don't treat this as a breaking change, since this data is con…
Please note that this release changes the data structure of the ssrExchange's
output. We don't treat this as a breaking change, since this data is considered
a private structure, but if your tests or other code relies on this, please check
the type changes and update it.
ssrExchange, for instance as a result of mutations by Graphcache. Instead the ssrExchange now serializes data early, by @kitten (See #962)Content-Type: application/json HTTP header when using GET in the fetchExchange, persistedFetchExchange, or multipartFetchExchange, by @JoviDeCroock (See #957)Remove whitespace and comments from string-queries, by @JoviDeCroock (See #911)
⚠️ Fix formatDocument mutating parts of the DocumentNode which may be shared by other documents and queries. Also ensure that a formatted document wil
formatDocument mutating parts of the DocumentNode which may be shared by other documents and queries. Also ensure that a formatted document will always generate the same key in createRequest as the original document, by @kitten (See #880)ssrExchange invalidating results on the client-side too eagerly, by delaying invalidation by a tick, by @kitten (See #885)⚠️ Fix timing for out-of-band client.reexecuteOperation calls. This would surface in asynchronous caching scenarios, where no result would be delivere
client.reexecuteOperation calls. This would surface in asynchronous caching scenarios, where no result would be delivered by the cache synchronously, while it still calls client.reexecuteOperation for e.g. a network-only request, which happens for cache-and-network. This issue becomes especially obvious in highly synchronous frameworks like Svelte, by @kitten (See #860)scheduleTask polyfill with inline Promise.resolve().then(fn) calls, by @kitten (See #861)As always, please ensure that you deduplicate @urql/core when upgrading. Additionally deduplicating the versions of wonka that you have installed may
As always, please ensure that you deduplicate @urql/core when upgrading. Additionally
deduplicating the versions of wonka that you have installed may also reduce your bundlesize.
client.subscription shortcut method, similar to client.query and client.mutation, by @FredyC (See #838)Add operationName to GET queries, by @jakubriedl (See #798)
Add source debug name to all dispatchDebug calls during build time to identify events by which exchange dispatched them, by @JoviDeCroock (See #780)
source debug name to all dispatchDebug calls during build time to identify events by which exchange dispatched them, by @JoviDeCroock (See #780)Add a "./package.json" entry to the package.json's "exports" field for Node 14. This seems to be required by packages like rollup-plugin-svelte to fun
"./package.json" entry to the package.json's "exports" field for Node 14. This seems to be required by packages like rollup-plugin-svelte to function properly, by @JoviDeCroock (See #771)Hoist variables in unminified build output for Metro Bundler builds which otherwise fails for process.env.NODE_ENV if-clauses, by @kitten (See #737)
process.env.NODE_ENV if-clauses, by @kitten (See #737)Sorry for the many updates; Please only upgrade to >=1.11.4 and don't use the deprecated 1.11.3 and 1.11.2 release.
Make the extension of the main export unknown, which fixes a Webpack issue where the resolver won't pick module fields in package.json files once it's
module fields in package.json files once it's importing from another .mjs file, by @JoviDeCroock (See #733)Nothing published for this version
⚠️ Fix missing @urql/core/internal entrypoint in the npm-release, which was previously not included, by @JoviDeCroock (See #731)
@urql/core/internal entrypoint in the npm-release, which was previously not included, by @JoviDeCroock (See #731)Add debugging events to exchanges that add more detailed information on what is happening internally, which will be displayed by devtools like the urq
Nothing published for this version
Pick modules from graphql package, instead of importing from graphql/index.mjs, by @kitten (See #700)
Add graphql@^15.0.0 to peer dependency range, by @kitten (See #688)
⚠️ Fix oversight in edge case for #662. The operation queue wasn't marked as being active which caused stale results and cache-and-network operations
⚠️ Fix critical bug in operation queueing that can lead to unexpected teardowns and swallowed operations. This would happen when a teardown operation
Refactor a couple of core helpers for minor bundlesize savings, by @kitten (See #658)
File or Blob. In this case stringifyVariables will now use a stable (but random) key, which means that mutations containing Files — or other objects like this — will now be distinct, as they should be, by @kitten (See #650)⚠️ Fix node resolution when using Webpack, which experiences a bug where it only resolves package.json:main instead of module when an .mjs file import
package.json:main instead of module when an .mjs file imports a package, by @JoviDeCroock (See #642)⚠️ Fix Node.js Module support for v13 (experimental-modules) and v14. If your bundler doesn't support .mjs files and fails to resolve the new version,
.mjs files and fails to resolve the new version, please double check your configuration for
Webpack, or similar tools, by @JoviDeCroock (See #637)Add a guard to "maskTypenames" so a null value isn't considered an object, by @JoviDeCroock (See #621)
⚠️ Fix Rollup bundle output being written to .es.js instead of .esm.js, by @kitten (See #609)
Add additionalTypenames to the OperationContext, which allows the document cache to invalidate efficiently when the __typename is unknown at the initi
additionalTypenames to the OperationContext, which allows the document cache to invalidate efficiently when the __typename is unknown at the initial fetch, by @JoviDeCroock (See #601) You can learn more about this change in our docs.Prevent active teardowns for queries on subscriptionExchange, by @kitten (See #577)
⚠️ Fix cache-only operations being forwarded and triggering fetch requests, by @JoviDeCroock (See #551)
cache-only operations being forwarded and triggering fetch requests, by @JoviDeCroock (See #551)One column per quarter.