QueryClient

An enhanced version of TanStack's Query QueryClient.
Adds specialized configurations for library entities like Query or Mutation.

Reference to source code

API Signature

import { QueryClient } from "@tanstack/query-core";

class QueryClient extends QueryClient {
  constructor(config?: QueryClientConfig);
}

Configuration

When creating an instance, you can provide:

import { DefaultOptions } from "@tanstack/query-core";

interface QueryClientConfig {
  defaultOptions?: DefaultOptions & {
    queries: QueryFeatures;
    mutations: MobxMutatonFeatures;
  };
  hooks?: QueryClientHooks;
}

Key methods and properties

queryFeatures

Features configurations exclusively for Query/InfiniteQuery

Example:

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      lazy: true,
      enableOnDemand: true,
      // resetOnDestroy: false,
      // dynamicOptionsUpdateDelay: undefined,
      throwOnError: true,
      refetchOnWindowFocus: false,
      refetchOnReconnect: false,
      staleTime: 0,
      retry: false,
      // transformError: (error) => error,
    },
  },
});

mutationFeatures

Features configurations exclusively for Mutation

Example:

export const queryClient = new QueryClient({
  defaultOptions: {
    mutations: {
      // invalidateByKey: true,
      // resetOnDestroy: true,
      lazy: true,
      // transformError: (error) => error,
    },
  },
});

hooks

Entity lifecycle events. Available hooks:

Hook	Description
onQueryInit	Triggered when a Query is created
onInfiniteQueryInit	Triggered when a InfiniteQuery is created
onMutationInit	Triggered when a Mutation is created
onQueryDestroy	Triggered when a Query is destroyed
onInfiniteQueryDestroy	Triggered when a InfiniteQuery is destroyed
onMutationDestroy	Triggered when a Mutation is destroyed

Inheritance

QueryClient inherits all methods and properties from QueryClient, including:

• getQueryData()
• setQueryData()
• invalidateQueries()
• prefetchQuery()
• cancelQueries()
• And others (see official documentation)

Usage Example

import { QueryClient } from "mobx-tanstack-query";

// Create a client with custom hooks
const client = new QueryClient({
  hooks: {
    onQueryInit: (query) => {
      console.log("[Init] Query:", query.queryKey);
    },
    onMutationDestroy: (mutation) => {
      console.log("[Destroy] Mutation:", mutation.options.mutationKey);
    },
  },
  defaultOptions: {
    queries: {
      enableOnDemand: true,
    },
    mutations: {
      invalidateByKey: true,
    },
  },
});

// Use standard QueryClient methods
const data = client.getQueryData(["todos"]);

When to Use?

Use QueryClient if you need:

• Customization of query/mutation lifecycle
• Tracking entity initialization/destruction events
• Advanced configuration for MobX-powered queries and mutations.

Persistence

If you need persistence you can use built-in TanStack query feature like createSyncStoragePersister or createAsyncStoragePersister
Follow this guide from original TanStack query documentation:
https://tanstack.com/query/latest/docs/framework/react/plugins/createSyncStoragePersister#api

Example of implementation

1. Install TanStack's persister dependencies:

npm

npm install @tanstack/query-async-storage-persister @tanstack/react-query-persist-client

pnpm

pnpm add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client

yarn

yarn add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client

2. Create QueryClient instance and attach "persistence" feature to it

import { QueryClient } from "mobx-tanstack-query";
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
import { persistQueryClient } from '@tanstack/react-query-persist-client';
import { compress, decompress } from 'lz-string'

export const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: Infinity } },
})

persistQueryClient({
  queryClient: queryClient as any,
  persister: createAsyncStoragePersister({
    storage: window.localStorage,
    serialize: (data) => compress(JSON.stringify(data)),
    deserialize: (data) => JSON.parse(decompress(data)),
  }),
  maxAge: Infinity,
});