Improve Tanstack Query Caching

Quickly improve performance in your web application by sharing a query cache across multiple tabs and windows.

Introduction

This package allows Tanstack Query state to be persisted using a SharedWorker. When a new tab or window is opened, its query cache can be populated with queries from another window.

Features

• Share a query cache between tabs and windows
• Reduce redundant network calls
• Simple configuration and setup
• Easy performance wins

A common use case is for access tokens. There is rarely a need for fetching a separate token for each new window. A shared query cache via SharedWorker will greatly improve application startup as a result.

Demo

A simple demo app has been published that demonstrates desired caching behaviour here: https://sjp.co.nz/projects/query-shared-worker-persister/demo

The source for the react application is available on GitHub

Getting Started

Installation

Install the package in your project using npm:

npm install @sjpnz/query-shared-worker-persister

Configuration

Follow these steps to configure QueryClient persistence. While the examples use React, a similar approach applies to other frameworks.

1. Create a QueryClient and SharedWorker persister:

   import { QueryClient } from "@tanstack/react-query";
   import { createSharedWorkerPersister } from "@sjpnz/query-shared-worker-persister";
   
   const queryClient = new QueryClient();
   const sharedWorkerPersister = createSharedWorkerPersister();

2. (Recommended) Use a broadcastQueryClient:

   For optimal performance and to ensure true global sharing of cached values across tabs, it's highly recommended to use a broadcastQueryClient. This prevents different tabs from overwriting each other's cached values, while also keeping the shared cache fresh.

   import { broadcastQueryClient } from "@tanstack/react-query-broadcast-client-experimental";
   
   broadcastQueryClient({ queryClient });

3. Use a persistQueryClient:

   Configure SharedWorker persistence via persistQueryClient. This will set up the shared cache.

   import { persistQueryClient } from '@tanstack/react-query-persist-client';
   
   persistQueryClient({
     queryClient,
     persister: sharedWorkerPersister
   });
   
   export default function App() {
     return (
       <QueryClientProvider
         client={queryClient}
       >
         <h1>Hello, world!</h1>
         {/* Your app components */}
       </QueryClientProvider>
     );
   }

Browser Support

This package relies on SharedWorker, which is available in modern desktop browsers but not in some environments such as Chrome on Android and certain in-app webviews.

When SharedWorker is unavailable, the persister degrades gracefully to a no-op storage: TanStack Query keeps working with its normal in-memory cache, just without cross-tab persistence. A single warning is logged to the console so the fallback is visible during development.

If you'd rather branch on support yourself — for example to skip wiring up persistence entirely — use the exported check:

import {
  createSharedWorkerPersister,
  isSharedWorkerSupported,
} from "@sjpnz/query-shared-worker-persister";

const persister = isSharedWorkerSupported() ? createSharedWorkerPersister() : undefined;

Disposal

Most apps keep a single persister for the page's lifetime and never need to dispose it. If you do recreate the persister (for example in tests, micro-frontends, or hot-module reloads), pass an AbortSignal to release the underlying SharedWorker connection when you're done:

const controller = new AbortController();
const persister = createSharedWorkerPersister({ signal: controller.signal });

// later, to tear it down:
controller.abort();

Recommendations

To get the most out of this package and ensure optimal performance, consider the following recommendations:

1. Configure staleTime for your queries

   Set an appropriate staleTime for effective caching. Without it, queries will not be loaded from the cache, negating the benefits of this package.

   See the following links for more details:

   • https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults
   • https://tkdodo.eu/blog/react-query-as-a-state-manager

   // Configure all queries to be considered stale after 5 minutes
   const STALE_TIME = 1000 * 60 * 5; // 5 minutes
   
   const queryClient = new QueryClient({
     defaultOptions: {
       queries: {
         staleTime: STALE_TIME,
       },
     },
   });

2. Use a Named Identifier for Your Application

   A unique identifier ensures that the cache remains relevant to your specific application, particularly when there are multiple applications running for a given origin.

   // Define a unique identifier for your application
   const APP_NAME = "MY_AWESOME_APP";
   
   // Configure the SharedWorker persister with the app-specific key
   const persister = createSharedWorkerPersister({
     key: APP_NAME,
   });
   
   // If using broadcastQueryClient, apply the same identifier
   broadcastQueryClient({
     queryClient,
     broadcastChannel: APP_NAME,
   });

   By default every application on an origin shares a single SharedWorker (and therefore a single in-memory store), with key namespacing the entry within it. If you want a fully isolated worker process per application — so that other same-origin apps can't read your cached values — pass a namespace as well:

   const persister = createSharedWorkerPersister({
     key: APP_NAME,
     namespace: APP_NAME, // dedicated SharedWorker, isolated from other apps on this origin
   });

3. Implement Cache Busting

   Provide an application version to invalidate the cache when it doesn't match the current application version. This ensures that outdated data isn't persisted when one tab/window has a newer application version than another.

   const APP_VERSION = "MY_AWESOME_APP_v1.2.3";
   
   const persistOptions = {
     persister: persister,
     buster: APP_VERSION,
   };
   
   export default function App() {
     return (
       <PersistQueryClientProvider
         client={queryClient}
         persistOptions={persistOptions}
       >
         <h1>Hello, world!</h1>
       </PersistQueryClientProvider>
     );
   }