Revert "refactor: replace queryClient prop with auto-detecting parent QueryClient"

This reverts commit 3ddb6f2.

Author: AliceR

README.md

@@ -35,7 +35,7 @@ If you do not install it, your package manager will warn you, and stac-react wil
 
 stac-react's hooks must be used inside children of a React context that provides access to the stac-react's core functionality.
 
-To get started, initialize `StacApiProvider` with the base URL of the STAC catalog. `StacApiProvider` automatically sets up a [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview) QueryClientProvider for you if one doesn't already exist in the component tree.
+To get started, initialize `StacApiProvider` with the base URL of the STAC catalog. `StacApiProvider` automatically sets up a [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview) QueryClientProvider for you, so you do not need to wrap your app with QueryClientProvider yourself.
 
 ```jsx
 import { StacApiProvider } from 'stac-react';
@@ -47,26 +47,19 @@ function StacApp() {
 }
 ```
 
-If you want to customize the QueryClient configuration (e.g., for custom caching behavior, retry logic, or global settings), wrap `StacApiProvider` with your own `QueryClientProvider`:
+If you want to provide your own custom QueryClient (for advanced caching or devtools), you can pass it as a prop:
 
 ```jsx
 import { StacApiProvider } from 'stac-react';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { QueryClient } from '@tanstack/react-query';
 
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutes
-      retry: 3,
-    },
-  },
-});
+const queryClient = new QueryClient();
 
 function StacApp() {
   return (
-    <QueryClientProvider client={queryClient}>
-      <StacApiProvider apiUrl="https://my-stac-api.com">{/* Other components */}</StacApiProvider>
-    </QueryClientProvider>
+    <StacApiProvider apiUrl="https://my-stac-api.com" queryClient={queryClient}>
+      {/* Other components */}
+    </StacApiProvider>
   );
 }
 ```
@@ -117,11 +110,9 @@ function StacApp() {
 
 ##### Component Properties
 
-| Option           | Type      | Description                                                                                   |
-| ---------------- | --------- | --------------------------------------------------------------------------------------------- |
-| `apiUrl`         | `string`  | The base url of the STAC catalog.                                                             |
-| `options`        | `object`  | Optional configuration object for customizing STAC API requests.                              |
-| `enableDevTools` | `boolean` | Optional. Enables TanStack Query DevTools browser extension integration. Defaults to `false`. |
+| Option    | Type     | Description                       |
+| --------- | -------- | --------------------------------- |
+| `apiUrl`. | `string` | The base url of the STAC catalog. |
 
 ### useCollections
 

docs/react-query-setup.md

@@ -8,45 +8,30 @@ stac-react relies on [TanStack Query](https://tanstack.com/query/latest/docs/fra
 - Ensures your app and stac-react share the same QueryClient instance.
 - Follows best practices for React libraries that integrate with popular frameworks.
 
-## QueryClient Management
+stac-react manages the QueryClient for you by default, but you can provide your own for advanced use cases.
 
-By default, `StacApiProvider` automatically creates and manages a QueryClient for you if one doesn't already exist in the component tree. This means you can use stac-react without any additional setup:
+**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.
 
-```jsx
-import { StacApiProvider } from 'stac-react';
-
-function App() {
-  return <StacApiProvider apiUrl="https://my-stac-api.com">{/* ...your app... */}</StacApiProvider>;
-}
-```
-
-### Custom QueryClient Configuration
-
-If you need custom QueryClient configuration (e.g., custom caching behavior, retry logic, or global settings), wrap `StacApiProvider` with your own `QueryClientProvider`:
+**Example:**
 
 ```jsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { StacApiProvider } from 'stac-react';
 
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 5 * 60 * 1000, // 5 minutes
-      retry: 3,
-    },
-  },
-});
+const queryClient = new QueryClient();
 
 function App() {
   return (
     <QueryClientProvider client={queryClient}>
-      <StacApiProvider apiUrl="https://my-stac-api.com">{/* ...your app... */}</StacApiProvider>
+      <StacApiProvider apiUrl="https://my-stac-api.com" queryClient={queryClient}>
+        {/* ...your app... */}
+      </StacApiProvider>
     </QueryClientProvider>
   );
 }
 ```
 
-`StacApiProvider` will automatically detect the parent QueryClient and use it instead of creating a new one.
+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
 

src/context/index.tsx

@@ -1,22 +1,23 @@
-import React, { useMemo, useContext } from 'react';
+import React, { useMemo } from 'react';
 import { StacApiContext } from './context';
 import { GenericObject } from '../types';
-import { QueryClient, QueryClientProvider, QueryClientContext } from '@tanstack/react-query';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 
 import useStacApi from '../hooks/useStacApi';
 
 type StacApiProviderType = {
   apiUrl: string;
   children: React.ReactNode;
   options?: GenericObject;
+  queryClient?: QueryClient;
   enableDevTools?: boolean;
 };
 
 function StacApiProviderInner({
   children,
   apiUrl,
   options,
-}: Omit<StacApiProviderType, 'enableDevTools'>) {
+}: Omit<StacApiProviderType, 'queryClient'>) {
   const { stacApi } = useStacApi(apiUrl, options);
 
   const contextValue = useMemo(
@@ -33,30 +34,19 @@ export function StacApiProvider({
   children,
   apiUrl,
   options,
+  queryClient,
   enableDevTools,
 }: StacApiProviderType) {
-  const existingClient = useContext(QueryClientContext);
   const defaultClient = useMemo(() => new QueryClient(), []);
+  const client: QueryClient = queryClient ?? defaultClient;
 
-  const client = existingClient ?? defaultClient;
-
-  // Setup DevTools once when component mounts or enableDevTools changes
-  useMemo(() => {
-    if (enableDevTools && typeof window !== 'undefined') {
-      window.__TANSTACK_QUERY_CLIENT__ = client;
-    }
-  }, [client, enableDevTools]);
-
-  if (existingClient) {
-    return (
-      <StacApiProviderInner apiUrl={apiUrl} options={options}>
-        {children}
-      </StacApiProviderInner>
-    );
+  if (enableDevTools && typeof window !== 'undefined') {
+    // Connect TanStack Query DevTools (browser extension)
+    window.__TANSTACK_QUERY_CLIENT__ = client;
   }
 
   return (
-    <QueryClientProvider client={defaultClient}>
+    <QueryClientProvider client={client}>
       <StacApiProviderInner apiUrl={apiUrl} options={options}>
         {children}
       </StacApiProviderInner>