How does setMutationDefaults work?

[charlestbell]

I am building a React Native Expo app. I've been using and loving Tanstack Query. Currently I'm implementing offline support.

I am confused by the use of setMutationDefaults. The docs say "If you persist offline mutations with the persistQueryClient plugin, mutations cannot be resumed when the page is reloaded unless you provide a default mutation function."
https://tanstack.com/query/v5/docs/framework/react/guides/mutations#persisting-offline-mutations

This paragraph does not explain enough for my brain to grok it. I can understand the need to arbitrarily add setMutationDefault for offline support to work. No worries there. But it seems to be more than a placeholde because it's actually querying stuff in the example.

// we need a default mutation function so that paused mutations can resume after a page reload
queryClient.setMutationDefaults(['todos'], {
  mutationFn: ({ id, data }) => {
    return api.updateTodo(id, data)
  },
})

What I don't understand is:

• Is the default function I pass taking the place of my real mutation functions?
• Is the default used for anything besides being a type of 'flag' for the resuming to work?
• What about all of my actual mutations I've written,. for all of my useMutations used throughout my app? Do they get run when paused mutations resume? If so, what is the default doing?
• It seems to be saying that all paused mutations will use this one default mutation function on resume. This seems unwieldy and confusing at best, near impossible at worst. I have 20+ mutations all doing different things and hitting different endpoints. I'm not sure how to even begin with melding them all into one default.

Thanks for the help

[TkDodo]

This paragraph does not explain enough for my brain to grok it.

The explanation is in the next paragraph:

This is a technical limitation. When persisting to an external storage, only the state of mutations is persisted, as functions cannot be serialized. After hydration, the component that triggers the mutation might not be mounted, so calling resumePausedMutations might yield an error: No mutationFn found.

But it seems to be more than a placeholde because it's actually querying stuff in the example.

Not sure what you mean with that. The example calls api.updateTodo(id, data), which isn not a query - it updates the todo.

Is the default function I pass taking the place of my real mutation functions?

yes.

Is the default used for anything besides being a type of 'flag' for the resuming to work?

defaults are applied to your mutation and merged with options passed to useMutation. Basically, there are three layers that get merged together:

• the defaultOptions you provide when creating the QueryClient. They match all mutations.
• the options you provide with setMutationDefaults. They match the passed key, fuzzily.
• the options you provide to useMutation

They are merged with a normal object spread, in that order:

{
  ...optionsFromQueryClient,
  ...optionsFromMutationDefaults,
  ...optionsFromUseMutation
}

What about all of my actual mutations I've written,. for all of my useMutations used throughout my app? Do they get run when paused mutations resume? If so, what is the default doing?

yes, if they are paused, they will run.

It seems to be saying that all paused mutations will use this one default mutation function on resume.

As said above, if you provide a mutationFn to useMutation, that will overwrite the default. Maybe a concrete example can help:

const queryClient = new QueryClient({
  defaultOptions: {
    mutations: {
      mutationFn: () => console.log('global default')
    }
  }
})

queryClient.setMutationDefaults(['a'], { mutationFn: () => console.log('key default') })

// this will use the global default, because nothing is provided
const { mutate } = useMutation()

// these will both use the key default, because the keys match
const { mutate } = useMutation({ mutationKey: ['a'] })
const { mutate } = useMutation({ mutationKey: ['a', 1] })

// this will use the provided fn because defaults are overwritten

const { mutate } = useMutation({ mutationKey: ['a'], mutationFn: () => console.log('I win!') })

[ys-sherzad]

@TkDodo
I'm struggling to understand how to set the default mutations if I have a number mutations that's persisting to be resumed. Are we setting a setMutationDefaults for each one of those mutation functions?

[TkDodo]

if they need a different function, yes.