refactor: replace queryClient prop with auto-detecting parent QueryClient

- Remove queryClient prop from StacApiProviderType
- Detect parent via QueryClientContext instead of accepting prop
- Update docs to show QueryClientProvider wrapping pattern
- Document missing options and enableDevTools props in API reference

This simplifies the API and prevents duplicate QueryClient instances.

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, so you do not need to wrap your app with QueryClientProvider yourself.
+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.
 
 ```jsx
 import { StacApiProvider } from 'stac-react';
@@ -47,19 +47,26 @@ function StacApp() {
 }
 ```
 
-If you want to provide your own custom QueryClient (for advanced caching or devtools), you can pass it as a prop:
+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`:
 
 ```jsx
 import { StacApiProvider } from 'stac-react';
-import { QueryClient } from '@tanstack/react-query';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 
-const queryClient = new QueryClient();
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5 * 60 * 1000, // 5 minutes
+      retry: 3,
+    },
+  },
+});
 
 function StacApp() {
   return (
-    <StacApiProvider apiUrl="https://my-stac-api.com" queryClient={queryClient}>
-      {/* Other components */}
-    </StacApiProvider>
+    <QueryClientProvider client={queryClient}>
+      <StacApiProvider apiUrl="https://my-stac-api.com">{/* Other components */}</StacApiProvider>
+    </QueryClientProvider>
   );
 }
 ```
@@ -110,9 +117,11 @@ function StacApp() {
 
 ##### Component Properties
 
-| Option    | Type     | Description                       |
-| --------- | -------- | --------------------------------- |
-| `apiUrl`. | `string` | The base url of the STAC catalog. |
+| 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`. |
 
 ### useCollections
 

docs/react-query-setup.md

@@ -8,30 +8,45 @@ 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.
 
-stac-react manages the QueryClient for you by default, but you can provide your own for advanced use cases.
+## QueryClient Management
 
-**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.
+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:
 
-**Example:**
+```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`:
 
 ```jsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { StacApiProvider } from 'stac-react';
 
-const queryClient = new QueryClient();
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5 * 60 * 1000, // 5 minutes
+      retry: 3,
+    },
+  },
+});
 
 function App() {
   return (
     <QueryClientProvider client={queryClient}>
-      <StacApiProvider apiUrl="https://my-stac-api.com" queryClient={queryClient}>
-        {/* ...your app... */}
-      </StacApiProvider>
+      <StacApiProvider apiUrl="https://my-stac-api.com">{/* ...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.
+`StacApiProvider` will automatically detect the parent QueryClient and use it instead of creating a new one.
 
 ## TanStack Query DevTools Integration
 

src/context/index.tsx

@@ -1,24 +1,23 @@
-import React, { useMemo, useState, useCallback } from 'react';
+import React, { useMemo, useState, useCallback, useContext } from 'react';
 import { StacApiContext } from './context';
 import type { CollectionsResponse, Item } from '../types/stac';
 import { GenericObject } from '../types';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { QueryClient, QueryClientProvider, QueryClientContext } 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, 'queryClient'>) {
+}: Omit<StacApiProviderType, 'enableDevTools'>) {
   const { stacApi } = useStacApi(apiUrl, options);
   const [collections, setCollections] = useState<CollectionsResponse>();
   const [items, setItems] = useState(new Map<string, Item>());
@@ -60,19 +59,30 @@ export function StacApiProvider({
   children,
   apiUrl,
   options,
-  queryClient,
   enableDevTools,
 }: StacApiProviderType) {
+  const existingClient = useContext(QueryClientContext);
   const defaultClient = useMemo(() => new QueryClient(), []);
-  const client: QueryClient = queryClient ?? defaultClient;
 
-  if (enableDevTools && typeof window !== 'undefined') {
-    // Connect TanStack Query DevTools (browser extension)
-    window.__TANSTACK_QUERY_CLIENT__ = client;
+  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>
+    );
   }
 
   return (
-    <QueryClientProvider client={client}>
+    <QueryClientProvider client={defaultClient}>
       <StacApiProviderInner apiUrl={apiUrl} options={options}>
         {children}
       </StacApiProviderInner>