react-query-setup.md

QueryClient Best Practice

stac-react relies on TanStack Query for data fetching and caching. To avoid duplicate React Query clients and potential version conflicts, stac-react lists @tanstack/react-query as a peer dependency.

Why peer dependency?

• Prevents multiple versions of React Query in your app.
• Ensures your app and stac-react share the same QueryClient instance.
• Follows best practices for React libraries that integrate with popular frameworks.

stac-react manages the QueryClient for you by default, but you can provide your own for advanced use cases.

Important: If your app uses multiple providers that require a TanStack QueryClient (such as QueryClientProvider and StacApiProvider), always use the same single QueryClient instance for all providers. This ensures that queries, mutations, and cache are shared across your app and prevents cache fragmentation or duplicate network requests.

Example:

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

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <StacApiProvider apiUrl="https://my-stac-api.com" queryClient={queryClient}>
        {/* ...your app... */}
      </StacApiProvider>
    </QueryClientProvider>
  );
}

If you do not pass the same QueryClient instance, each provider will maintain its own cache, which can lead to unexpected behavior.

TanStack Query DevTools Integration

stac-react automatically connects your QueryClient to the TanStack Query DevTools browser extension when running in development mode. This allows you to inspect queries, mutations, and cache directly in your browser without adding extra dependencies to your project.

How it works:

• In development (process.env.NODE_ENV === 'development'), stac-react exposes the QueryClient on window.__TANSTACK_QUERY_CLIENT__.
• The browser extension detects this and connects automatically.
• No code changes or additional dependencies are required.

By default, React Query Devtools are only included in bundles when process.env.NODE_ENV === 'development', so you don't need to worry about excluding them during a production build.

Alternative:

• If you prefer an embedded/floating devtools panel, you can install and use the TanStack Query Devtools React component in your app. This adds a UI panel directly to your app, but increases bundle size and dependencies.

For more details, see the TanStack Query DevTools documentation.