Using QueryClient defaultOptions.meta to inject Axios instance - Is this a good pattern?

[FR073N]

Context

I'm working on a feature for orval (OpenAPI code generator) to allow axios instance injection in generated React Query hooks. Before implementing it, I wanted to validate the approach with the community.

Feature request: orval-labs/orval#2887

The pattern I'm using

I store my configured axios instance in QueryClient.defaultOptions.meta and retrieve it in my hooks:

// Setup
const apiClient = axios.create({ baseURL: '/api' });
apiClient.interceptors.request.use(addAuthHeader);
apiClient.interceptors.response.use(handleTokenRefresh);

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      meta: { axiosInstance: apiClient },
    },
    mutations: {
      meta: { axiosInstance: apiClient },
    },
  },
});

// Helper to retrieve axios instance (with fallback)
const getQueryAxiosInstance = (queryClient: QueryClient): AxiosInstance => {
  try {
    const instance = queryClient.getDefaultOptions()?.queries?.meta?.axiosInstance;
    return (instance as AxiosInstance) ?? axios;
  } catch {
    return axios;
  }
};

const getMutationAxiosInstance = (queryClient: QueryClient): AxiosInstance => {
  try {
    const instance = queryClient.getDefaultOptions()?.mutations?.meta?.axiosInstance;
    return (instance as AxiosInstance) ?? axios;
  } catch {
    return axios;
  }
};

// Usage in hooks
const useListPets = (params?: ListPetsParams) => {
  const queryClient = useQueryClient();
  const axiosInstance = getQueryAxiosInstance(queryClient);

  return useQuery({
    queryKey: ['pets', params],
    queryFn: ({ signal }) =>
      axiosInstance.get('/pets', { params, signal }).then(r => r.data),
  });
};

const useCreatePet = () => {
  const queryClient = useQueryClient();
  const axiosInstance = getMutationAxiosInstance(queryClient);

  return useMutation({
    mutationFn: (data) =>
      axiosInstance.post('/pets', data).then(r => r.data),
  });
};

Why this pattern?

I originally implemented this pattern because I'm using Next.js with the Pages Router in SSR mode, and I needed two different axios instances:

• one for server-side requests (with server-specific headers, internal URLs)
• and one for client-side requests (with browser cookies, error interceptors, public URLs).

With this approach, I can configure each QueryClient with its own axios instance depending on the context:

// Server-side (getServerSideProps)
const serverAxios = axios.create({
  baseURL: process.env.INTERNAL_API_URL,
  headers: { 'X-Internal-Token': process.env.SERVICE_TOKEN }
});

const queryClient = new QueryClient({
  defaultOptions: {
    queries: { meta: { axiosInstance: serverAxios } },
  },
});

// Client-side
const clientAxios = axios.create({
  baseURL: '/api',
  withCredentials: true
});

const queryClient = new QueryClient({
  defaultOptions: {
    queries: { meta: { axiosInstance: clientAxios } },
    mutations: { meta: { axiosInstance: clientAxios } },
  },
});

Now I want to take it further: I'm planning to publish my backend API as an SDK package on NPM. The idea is that consumers of my SDK can inject their own axios instance at runtime with their own configuration (auth interceptors, base URL, error handling, etc.). This pattern makes it possible without any tight coupling.

Questions

1. Is using defaultOptions.queries.meta and defaultOptions.mutations.meta a recommended way to share context like an HTTP client?

2. Any performance concerns with calling queryClient.getDefaultOptions() on every hook render?

3. Is there a better alternative I should consider?

I've been using this pattern in production for a while and it works well. If the approach is validated, I'll implement it in orval so the community can benefit from it.

Thanks!

[TkDodo]

Hm, I don’t think defaultOptions is meant to be used that way. The problem with this approach:

const useListPets = (params?: ListPetsParams) => {
  const queryClient = useQueryClient();
  const axiosInstance = getQueryAxiosInstance(queryClient);

  return useQuery({
    queryKey: ['pets', params],
    queryFn: ({ signal }) =>
      axiosInstance.get('/pets', { params, signal }).then(r => r.data),
  });
};

is that you create a closure over axiosInstance and might read stale value during refetches. The eslint-plugin-query/exhaustive-deps eslint rule should also tell you that axiosInstance is a dependency that needs to go into the queryKey.

You can fix this by always reading the latest value in the queryFn from the injected client:

const useListPets = (params?: ListPetsParams) => {
  return useQuery({
    queryKey: ['pets', params],
    queryFn: ({ signal, client }) =>
      getQueryAxiosInstance(client).get('/pets', { params, signal }).then(r => r.data),
  });
};

this should be safe.

The way meta is meant to be used is that we also inject it to the queryFn, so you could also do:

const useListPets = (params?: ListPetsParams) => {
  return useQuery({
    queryKey: ['pets', params],
    queryFn: ({ signal, meta }) =>
      meta.axiosInstance.get('/pets', { params, signal }).then(r => r.data),
  });
};

The problem here is that meta set by defaultOptions will be fully overwritten if a user passes meta in. I think we’d want to do a shallow merging in the future to fix this, but for now, calling getQueryAxiosInstance(client) in the queryFn seems like the best approach.

[FR073N]

Thanks for the feedback @TkDodo!

Just to make sure I understand correctly - moving the getQueryAxiosInstance call inside the queryFn would fix the stale closure issue, right?

// ❌ Current pattern (potential stale closure)
const useListPets = () => {
  const queryClient = useQueryClient();
  const axiosInstance = getQueryAxiosInstance(queryClient); // Read once at render

  return useQuery({
    queryKey: ['pets'],
    queryFn: () => axiosInstance.get('/pets'), // Closure over potentially stale value
  });
};

// ✅ Recommended pattern (always fresh)
const useListPets = () => {
  const queryClient = useQueryClient();

  return useQuery({
    queryKey: ['pets'],
    queryFn: () => {
      // Read on every queryFn execution = always latest value
      const axiosInstance = getQueryAxiosInstance(queryClient);
      return axiosInstance.get('/pets');
    },
  });
};

And with this fix, is storing an axios instance in defaultOptions.meta and reading it in hooks a valid pattern? I want to make sure this is a good approach before building on top of it.

Thanks again for taking the time to review this!

[TkDodo]

Just to make sure I understand correctly - moving the getQueryAxiosInstance call inside the queryFn would fix the stale closure issue, right?

yes

is storing an axios instance in defaultOptions.meta and reading it in hooks a valid pattern?

the only thing that’s not ideal is that meta is part of hydration, so it should usually be serializable. If you put an axios instance there, users doing SSR or persistence might run into issues.

[FR073N]

Just to make sure - since we're using defaultOptions.meta (not the meta on individual queries), and dehydrate() only serializes the query cache (not the QueryClient's defaultOptions), would this still be an issue?

In my SSR setup, I create separate QueryClient instances on server and client, each with their own axios instance in defaultOptions.meta. The dehydrated state only contains the cached data, not the axios instance.

// Server (getServerSideProps)
const serverQueryClient = new QueryClient({
  defaultOptions: { queries: { meta: { axiosInstance: serverAxios } } }
});
await prefetchListPets(serverQueryClient);
return { props: { dehydratedState: dehydrate(serverQueryClient) } };
// dehydrate() serializes cache only, not defaultOptions

// Client
const clientQueryClient = new QueryClient({
  defaultOptions: { queries: { meta: { axiosInstance: clientAxios } } }
});
// HydrationBoundary rehydrates the cache, not defaultOptions

Am I understanding this correctly?

[TkDodo]

since we're using defaultOptions.meta (not the meta on individual queries)

defaultOptions is just a way to set meta when it’s not set on useQuery. One can always pass meta to useQuery and that would overwrite meta.

Also, when a query is created, it gets the defaultOptions applied, so the meta on the query will contain the axios instance when this is set as default.

The dehydrated state only contains the cached data, not the axios instance.

I’m pretty sure the dehydrated state would also contain the axios instance.

[FR073N]

You're right! I just tested it and the meta is indeed included in the dehydrated state.

However, I noticed that JSON.stringify simply ignores functions - so the axios instance doesn't actually end up in the serialized HTML:

// Test result:
Meta value: { axiosInstance: [Function: wrap] ... }

// After JSON.stringify:
"meta":{}  // Functions are stripped out

So there's no data leak or crash - the serialization works, it just results in an empty meta object on the client after hydration.

Since we create a fresh QueryClient on the client with its own axios instance in defaultOptions.meta, I think this is fine? The hydrated data gets the correct axios from the client's QueryClient config, not from the dehydrated state.

Or am I missing something here?