feat: Support the ability to provide a context (#2548)

* Support providing a context

* Addressing comments and merge conflicts from rebase

Author: blackarctic

.vscode/settings.json

@@ -18,6 +18,7 @@ import { ReactQueryDevtools } from 'react-query/devtools'
 ```
 
 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.
+
 ## Floating Mode
 
 Floating Mode will mount the devtools as a fixed, floating element in your app and provide a toggle in the corner of the screen to show and hide the devtools. This toggle state will be stored and remembered in localStorage across reloads.
@@ -50,6 +51,8 @@ function App() {
 - `position?: "top-left" | "top-right" | "bottom-left" | "bottom-right"`
   - Defaults to `bottom-left`
   - The position of the React Query logo to open and close the devtools panel
+- `context?: React.Context<QueryClient | undefined>`
+  - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.
 
 ## Embedded Mode
 

docs/src/pages/devtools.md

@@ -346,3 +346,90 @@ When using the [functional updater form of setQueryData](../reference/QueryClien
    (previousTodo) => previousTodo ? { ...previousTodo, done: true } : undefined
 )
  ```
+
+ ### Custom Contexts for Multiple Providers
+
+Custom contexts can now be specified to pair hooks with their matching `Provider`. This is critical when there may be multiple React Query `Provider` instances in the component tree and you need to ensure your hook uses the correct `Provider` instance.
+
+An example:
+
+1) Create a data package.
+
+```tsx
+// Our first data package: @my-scope/container-data
+
+const context = React.createContext<QueryClient | undefined>();
+const queryCache = new QueryCache()
+const queryClient = new QueryClient({ queryCache, context })
+
+
+export const useUser = () => {
+  return useQuery(USER_KEY, USER_FETCHER, {
+    context,
+  })
+}
+
+export const ContainerDataProvider: React.FC = ({ children }) => {
+  return (
+    <QueryClientProvider client={queryClient} context={context}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+
+```
+
+2) Create a second data package.
+
+```tsx
+// Our second data package: @my-scope/my-component-data
+
+const context = React.createContext<QueryClient | undefined>();
+const queryCache = new QueryCache()
+const queryClient = new QueryClient({ queryCache, context })
+
+
+export const useItems = () => {
+  return useQuery(ITEMS_KEY, ITEMS_FETCHER, {
+    context,
+  })
+}
+
+export const MyComponentDataProvider: React.FC = ({ children }) => {
+  return (
+    <QueryClientProvider client={queryClient} context={context}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+
+```
+
+3) Use these two data packages in your application.
+
+```tsx
+// Our application
+
+import { ContainerDataProvider, useUser } from "@my-scope/container-data";
+import { AppDataProvider } from "@my-scope/app-data";
+import { MyComponentDataProvider, useItems } from "@my-scope/my-component-data";
+
+<ContainerDataProvider> // <-- Provides container data (like "user") using its own React Query provider
+  ...
+  <AppDataProvider> // <-- Provides app data using its own React Query provider (unused in this example)
+    ...
+      <MyComponentDataProvider> // <-- Provides component data (like "items") using its own React Query provider
+        <MyComponent />
+      </MyComponentDataProvider>
+    ...
+  </AppDataProvider>
+  ...
+</ContainerDataProvider>
+
+// Example of hooks provided by the "DataProvider" components above:
+const MyComponent = () => {
+  const user = useUser(); // <-- Uses the context specified in ContainerDataProvider.
+  const items = useItems(); // <-- Uses the context specified in MyComponentDataProvider
+  ...
+}
+```

docs/src/pages/guides/migrating-to-react-query-4.md

@@ -14,11 +14,14 @@ function App() {
   return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
 }
 ```
+
 **Options**
 
 - `client: QueryClient`
   - **Required**
   - the QueryClient instance to provide
 - `contextSharing: boolean`
   - defaults to `false`
-  - Set this to `true` to enable context sharing, which will share the first and at least one instance of the context across the window  to ensure that if React Query is used across  different bundles or microfrontends they will  all use the same **instance** of context, regardless of module scoping.
+  - Set this to `true` to enable context sharing, which will share the first and at least one instance of the context across the window to ensure that if React Query is used across different bundles or microfrontends they will all use the same **instance** of context, regardless of module scoping.
+- `context?: React.Context<QueryClient | undefined>`
+  - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.

docs/src/pages/reference/QueryClientProvider.md

@@ -84,6 +84,8 @@ hydrate(queryClient, dehydratedState, options)
     - Optional
     - `mutations: MutationOptions` The default mutation options to use for the hydrated mutations.
     - `queries: QueryOptions` The default query options to use for the hydrated queries.
+  - `context?: React.Context<QueryClient | undefined>`
+    - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.
 
 ### Limitations
 
@@ -108,6 +110,8 @@ useHydrate(dehydratedState, options)
   - Optional
   - `defaultOptions: QueryOptions`
     - The default query options to use for the hydrated queries.
+  - `context?: React.Context<QueryClient | undefined>`
+    - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.
 
 ## `Hydrate`
 
@@ -129,3 +133,5 @@ function App() {
   - Optional
   - `defaultOptions: QueryOptions`
     - The default query options to use for the hydrated queries.
+  - `context?: React.Context<QueryClient | undefined>`
+    - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.

docs/src/pages/reference/hydration.md

@@ -17,6 +17,8 @@ const isFetchingPosts = useIsFetching(['posts'])
 
 - `queryKey?: QueryKey`: [Query Keys](../guides/query-keys)
 - `filters?: QueryFilters`: [Query Filters](../guides/filters#query-filters)
+- `context?: React.Context<QueryClient | undefined>`
+  - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.
 
 **Returns**
 

docs/src/pages/reference/useIsFetching.md

@@ -17,6 +17,8 @@ const isMutatingPosts = useIsMutating(['posts'])
 
 - `mutationKey?: string | unknown[]`
 - `filters?: MutationFilters`: [Mutation Filters](../guides/filters#mutation-filters)
+- `context?: React.Context<QueryClient | undefined>`
+  - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.
 
 **Returns**
 

docs/src/pages/reference/useIsMutating.md

@@ -87,6 +87,8 @@ mutate(variables, {
 - `meta: Record<string, unknown>`
   - Optional
   - If set, stores additional information on the mutation cache entry that can be used as needed. It will be accessible wherever the `mutation` is available (eg. `onError`, `onSuccess` functions of the `MutationCache`).
+- `context?: React.Context<QueryClient | undefined>`
+  - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.
 
 **Returns**
 

docs/src/pages/reference/useMutation.md

@@ -16,7 +16,10 @@ const results = useQueries({
 
 **Options**
 
-The `useQueries` hook accepts an options object with a **queries** key whose value is an array with query option objects identical to the [`useQuery` hook](/reference/useQuery).
+The `useQueries` hook accepts an options object with a **queries** key whose value is an array with query option objects identical to the [`useQuery` hook](/reference/useQuery) (excluding the `context` option).
+
+- `context?: React.Context<QueryClient | undefined>`
+  - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.
 
 **Returns**
 

docs/src/pages/reference/useQueries.md

@@ -184,6 +184,8 @@ const result = useQuery({
 - `meta: Record<string, unknown>`
   - Optional
   - If set, stores additional information on the query cache entry that can be used as needed. It will be accessible wherever the `query` is available, and is also part of the `QueryFunctionContext` provided to the `queryFn`.
+- `context?: React.Context<QueryClient | undefined>`
+  - Use this to use a custom React Query context. Otherwise, `defaultContext` will be used.
 
 **Returns**