query feat(query-core): add MutationFunctionContext argument to mutateFn

This PR adds new argument to mutateFn allowing for access to queryClient as well as meta object.

This feature should make it easier to attach authentication headers from within mutateFn, that would typically live in QueryCache. Currently that's made very difficult and requires either having singleton context in the codebase or requiring consumers of mutations to pass auth token each time.

This PR also makes it more similar to how queryFn behaves, in that it accepts QueryFunctionContext.

Note: I wasn't entirely sure about the name of MutateFunctionContext, but ultimately I decided to go ahead with that name to mirror the way queryFn behaves. I realise this might be suboptimal, due to there already existing a TContext for mutations. Happy to discuss and take direction here.

May 27 '25 06:05 travikk

we already have a PR for this:

https://github.com/TanStack/query/pull/7343

can we consolidate the work in one PR?

I think we’d want 3 properties passed:

- mutationKey
- meta
- client

Jun 02 '25 15:06 TkDodo

@TkDodo updated as requested

Jun 03 '25 04:06 travikk

View your CI Pipeline Execution ↗ for commit 2c1a713843838739cce659e07da06d5748aee1cc.

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	❌ Failed	2m 21s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	1m 22s	View ↗

☁️ Nx Cloud last updated this comment at 2025-06-19 08:32:16 UTC

Jun 19 '25 08:06 nx-cloud[bot]

More templates

@tanstack/angular-query-devtools-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-devtools-experimental@9193

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@9193

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@9193

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@9193

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@9193

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@9193

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@9193

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@9193

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@9193

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@9193

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@9193

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@9193

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@9193

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@9193

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@9193

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@9193

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@9193

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@9193

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@9193

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@9193

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@9193

commit: 2c1a713

Jun 19 '25 08:06 pkg-pr-new[bot]

We're quite interested in utilising this new feature at Sanity as part of our own abstraction for a SanityQueryClient – is there anything to do to help push this PR forward? Is it just the naming of context vs scope or more...?

Sep 02 '25 21:09 joshuaellis

@joshuaellis I’m fine with the scope renaming of what gets returned from onMutate. Then, we can have context for what gets passed to the mutationFn as second argument. I think it just needs to be done. If you want to open another PR to get it over the finish line, please do.

Sep 03 '25 08:09 TkDodo

superseded by:

https://github.com/TanStack/query/pull/9615

Sep 05 '25 14:09 TkDodo