Enhance meta documentation

[thomasneger]

Hi TanStack team,

Delightful library. I am on the process of migrating our monorepo code base to @tanstack/react-query and have been absolutely loving it.

I was setting up our meta object, in our project. We have a lot of constants that we use everywhere in our network queries and I'm very thankful to have access to that meta object in all the api of the library. It might be a bit of a niche feature, but for us it's very useful.

I just got really confused when the meta object I defined in the QueryClient defaultOptions, was not available in the useMutation mutationFn as it does within the useQuery queryFn.

Here is the shortest example I could put together which illustrates my confusion:

import {
  QueryClient,
  QueryClientProvider,
  useMutation,
} from '@tanstack/react-query';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: { meta: { foo: 'bar' } },
  },
});

export function MetaUndefinedError() {
  return (
    <QueryClientProvider client={queryClient}>
      <Component />
    </QueryClientProvider>
  );
}

function Component() {
  const { mutate } = useMutation({
    mutationKey: ['test'],
    mutationFn: async (_variables, { meta }) => {
      console.log(meta); // I expected this to log: { foo: 'bar' } but it is undefined
    },
  });

  return <button onClick={() => mutate()}>Test</button>;
}

I was actually about to create an issue for this, until, by poking around, I realized that the QueryClient config is split and I have to pass meta to both the queries and mutations configs :

const queryClient = new QueryClient({
  defaultOptions: {
    queries: { meta: { foo: 'bar' } },
    mutations: { meta: { foo: 'bar' } }, // this is then available in `useMutation`
});

The documentation around meta I could find is mostly about typing, which if you read between the lines, kind of shows that meta has to be typed in 2 places.

Maybe an extra documentation page on how to setup meta in general could help. If you have been using TanStack Query for a while you would probably know about this. But for me who is completely new and didn't yet have a use case to configure the mutations settings, it was not obvious at all 😄.

Thanks for reading. Keep on keeping on.