diff --git a/docs/framework/react/guides/dependent-queries.md b/docs/framework/react/guides/dependent-queries.md index acbf4584d5..0326873d72 100644 --- a/docs/framework/react/guides/dependent-queries.md +++ b/docs/framework/react/guides/dependent-queries.md @@ -90,6 +90,6 @@ const usersMessages = useQueries({ ## A note about performance -Dependent queries by definition constitutes a form of [request waterfall](../../../react/guides/request-waterfalls), which hurts performance. If we pretend both queries take the same amount of time, doing them serially instead of in parallel always takes twice as much time, which is especially hurtful when it happens on a client that has high latency. If you can, it's always better to restructure the backend APIs so that both queries can be fetched in parallel, though that might not always be practically feasible. +Dependent queries by definition constitutes a form of [request waterfall](./request-waterfalls), which hurts performance. If we pretend both queries take the same amount of time, doing them serially instead of in parallel always takes twice as much time, which is especially hurtful when it happens on a client that has high latency. If you can, it's always better to restructure the backend APIs so that both queries can be fetched in parallel, though that might not always be practically feasible. In the example above, instead of first fetching `getUserByEmail` to be able to `getProjectsByUser`, introducing a new `getProjectsByUserEmail` query would flatten the waterfall. diff --git a/docs/framework/react/guides/initial-query-data.md b/docs/framework/react/guides/initial-query-data.md index 1f39cd3ca4..b92a6b4286 100644 --- a/docs/framework/react/guides/initial-query-data.md +++ b/docs/framework/react/guides/initial-query-data.md @@ -8,8 +8,8 @@ There are many ways to supply initial data for a query to the cache before you n - Declaratively: - Provide `initialData` to a query to prepopulate its cache if empty - Imperatively: - - [Prefetch the data using `queryClient.prefetchQuery`](../../../react/guides/prefetching) - - [Manually place the data into the cache using `queryClient.setQueryData`](../../../react/guides/prefetching) + - [Prefetch the data using `queryClient.prefetchQuery`](./prefetching) + - [Manually place the data into the cache using `queryClient.setQueryData`](./prefetching) ## Using `initialData` to prepopulate a query diff --git a/docs/framework/react/guides/migrating-to-react-query-3.md b/docs/framework/react/guides/migrating-to-react-query-3.md index e41a441bc6..011dc795ab 100644 --- a/docs/framework/react/guides/migrating-to-react-query-3.md +++ b/docs/framework/react/guides/migrating-to-react-query-3.md @@ -103,8 +103,8 @@ try { Together, these provide the same experience as before, but with added control to choose which component trees you want to reset. For more information, see: -- [QueryErrorResetBoundary](../../reference/QueryErrorResetBoundary) -- [useQueryErrorResetBoundary](../../reference/useQueryErrorResetBoundary) +- [QueryErrorResetBoundary](../reference/QueryErrorResetBoundary) +- [useQueryErrorResetBoundary](../reference/useQueryErrorResetBoundary) ### `QueryCache.getQuery()` has been replaced by `QueryCache.find()`. diff --git a/docs/framework/react/guides/migrating-to-react-query-4.md b/docs/framework/react/guides/migrating-to-react-query-4.md index 7ba6fa7d43..84c40cd040 100644 --- a/docs/framework/react/guides/migrating-to-react-query-4.md +++ b/docs/framework/react/guides/migrating-to-react-query-4.md @@ -58,9 +58,9 @@ Please note in the case of `TypeScript` you need to use `tsx` as the parser; oth ### Query Keys (and Mutation Keys) need to be an Array -In v3, Query and Mutation Keys could be a String or an Array. Internally, React Query has always worked with Array Keys only, and we've sometimes exposed this to consumers. For example, in the `queryFn`, you would always get the key as an Array to make working with [Default Query Functions](../default-query-function) easier. +In v3, Query and Mutation Keys could be a String or an Array. Internally, React Query has always worked with Array Keys only, and we've sometimes exposed this to consumers. For example, in the `queryFn`, you would always get the key as an Array to make working with [Default Query Functions](./default-query-function) easier. -However, we have not followed this concept through to all apis. For example, when using the `predicate` function on [Query Filters](../filters) you would get the raw Query Key. This makes it difficult to work with such functions if you use Query Keys that are mixed Arrays and Strings. The same was true when using global callbacks. +However, we have not followed this concept through to all apis. For example, when using the `predicate` function on [Query Filters](./filters) you would get the raw Query Key. This makes it difficult to work with such functions if you use Query Keys that are mixed Arrays and Strings. The same was true when using global callbacks. To streamline all apis, we've decided to make all keys Arrays only: @@ -100,7 +100,7 @@ Please note in the case of `TypeScript` you need to use `tsx` as the parser; oth ### The idle state has been removed -With the introduction of the new [fetchStatus](../queries#fetchstatus) for better offline support, the `idle` state became irrelevant, because `fetchStatus: 'idle'` captures the same state better. For more information, please read [Why two different states](../queries#why-two-different-states). +With the introduction of the new [fetchStatus](./queries#fetchstatus) for better offline support, the `idle` state became irrelevant, because `fetchStatus: 'idle'` captures the same state better. For more information, please read [Why two different states](./queries#why-two-different-states). This will mostly affect `disabled` queries that don't have any `data` yet, as those were in `idle` state before: @@ -110,7 +110,7 @@ This will mostly affect `disabled` queries that don't have any `data` yet, as th + fetchStatus: 'idle' // [!code ++] ``` -Also, have a look at [the guide on dependent queries](../dependent-queries) +Also, have a look at [the guide on dependent queries](./dependent-queries) #### disabled queries @@ -121,7 +121,7 @@ Due to this change, disabled queries (even temporarily disabled ones) will start isInitialLoading // [!code ++] ``` -See also the guide on [disabling queries](../disabling-queries#isInitialLoading) +See also the guide on [disabling queries](./disabling-queries#isInitialLoading) ### new API for `useQueries` @@ -142,7 +142,7 @@ The `useQueries` hook now accepts an object with a `queries` prop as its input. ### Undefined is an illegal cache value for successful queries -In order to make bailing out of updates possible by returning `undefined`, we had to make `undefined` an illegal cache value. This is in-line with other concepts of react-query, for example, returning `undefined` from the [initialData function](../initial-query-data#initial-data-function) will also _not_ set data. +In order to make bailing out of updates possible by returning `undefined`, we had to make `undefined` an illegal cache value. This is in-line with other concepts of react-query, for example, returning `undefined` from the [initialData function](./initial-query-data#initial-data-function) will also _not_ set data. Further, it is an easy bug to produce `Promise` by adding logging in the queryFn: @@ -156,7 +156,7 @@ This is now disallowed on type level; at runtime, `undefined` will be transforme ### Queries and mutations, per default, need network connection to run -Please read the [New Features announcement](#proper-offline-support) about online / offline support, and also the dedicated page about [Network mode](../network-mode) +Please read the [New Features announcement](#proper-offline-support) about online / offline support, and also the dedicated page about [Network mode](./network-mode) Even though React Query is an Async State Manager that can be used for anything that produces a Promise, it is most often used for data fetching in combination with data fetching libraries. That is why, per default, queries and mutations will be `paused` if there is no network connection. If you want to opt-in to the previous behavior, you can globally set `networkMode: offlineFirst` for both queries and mutations: @@ -242,7 +242,7 @@ The filter defaults to `all`, and you can choose to only match `active` or `inac #### refetchActive / refetchInactive -[queryClient.invalidateQueries](../../../../reference/QueryClient/#queryclientinvalidatequeries) had two additional, similar flags: +[queryClient.invalidateQueries](../../../reference/QueryClient#queryclientinvalidatequeries) had two additional, similar flags: ``` refetchActive: Boolean @@ -280,7 +280,7 @@ React.useEffect(() => mySideEffectHere(data), [data]) ### `persistQueryClient` and the corresponding persister plugins are no longer experimental and have been renamed -The plugins `createWebStoragePersistor` and `createAsyncStoragePersistor` have been renamed to [`createSyncStoragePersister`](../../plugins/createSyncStoragePersister) and [`createAsyncStoragePersister`](../../plugins/createAsyncStoragePersister) respectively. The interface `Persistor` in `persistQueryClient` has also been renamed to `Persister`. Checkout [this stackexchange](https://english.stackexchange.com/questions/206893/persister-or-persistor) for the motivation of this change. +The plugins `createWebStoragePersistor` and `createAsyncStoragePersistor` have been renamed to [`createSyncStoragePersister`](..//plugins/createSyncStoragePersister) and [`createAsyncStoragePersister`](../plugins/createAsyncStoragePersister) respectively. The interface `Persistor` in `persistQueryClient` has also been renamed to `Persister`. Checkout [this stackexchange](https://english.stackexchange.com/questions/206893/persister-or-persistor) for the motivation of this change. Since these plugins are no longer experimental, their import paths have also been updated: @@ -296,7 +296,7 @@ Since these plugins are no longer experimental, their import paths have also bee ### The `cancel` method on promises is no longer supported -The [old `cancel` method](../query-cancellation#old-cancel-function) that allowed you to define a `cancel` function on promises, which was then used by the library to support query cancellation, has been removed. We recommend to use the [newer API](../query-cancellation) (introduced with v3.30.0) for query cancellation that uses the [`AbortController` API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) internally and provides you with an [`AbortSignal` instance](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for your query function to support query cancellation. +The [old `cancel` method](./query-cancellation#old-cancel-function) that allowed you to define a `cancel` function on promises, which was then used by the library to support query cancellation, has been removed. We recommend to use the [newer API](./query-cancellation) (introduced with v3.30.0) for query cancellation that uses the [`AbortController` API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) internally and provides you with an [`AbortSignal` instance](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for your query function to support query cancellation. ### TypeScript @@ -304,7 +304,7 @@ Types now require using TypeScript v4.1 or greater ### Supported Browsers -As of v4, React Query is optimized for modern browsers. We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements [here](../../installation#requirements). +As of v4, React Query is optimized for modern browsers. We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements [here](../installation#requirements). ### `setLogger` is removed @@ -427,7 +427,7 @@ React Query defaults to "tracking" query properties, which should give you a nic ### Bailing out of updates with setQueryData -When using the [functional updater form of setQueryData](../../../../reference/QueryClient/#queryclientsetquerydata), you can now bail out of the update by returning `undefined`. This is helpful if `undefined` is given to you as `previousValue`, which means that currently, no cached entry exists and you don't want to / cannot create one, like in the example of toggling a todo: +When using the [functional updater form of setQueryData](../../../reference/QueryClient#queryclientsetquerydata), you can now bail out of the update by returning `undefined`. This is helpful if `undefined` is given to you as `previousValue`, which means that currently, no cached entry exists and you don't want to / cannot create one, like in the example of toggling a todo: ```tsx queryClient.setQueryData(['todo', id], (previousTodo) => diff --git a/docs/framework/react/guides/migrating-to-v5.md b/docs/framework/react/guides/migrating-to-v5.md index 8a1982444a..6bbe17bc9c 100644 --- a/docs/framework/react/guides/migrating-to-v5.md +++ b/docs/framework/react/guides/migrating-to-v5.md @@ -169,7 +169,7 @@ Custom loggers were already deprecated in 4 and have been removed in this versio ### Supported Browsers -We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements [here](../../installation#requirements). +We have updated our browserslist to produce a more modern, performant and smaller bundle. You can read about the requirements [here](../installation#requirements). ### Private class fields and methods @@ -218,7 +218,7 @@ useQuery({ }) ``` -For a way to set a different kind of Error globally, see [the TypeScript Guide](../../typescript#registering-a-global-error). +For a way to set a different kind of Error globally, see [the TypeScript Guide](../typescript#registering-a-global-error). ### eslint `prefer-query-object-syntax` rule is removed @@ -494,21 +494,21 @@ Note that the infinite list must be bi-directional, which requires both `getNext ### Infinite Queries can prefetch multiple pages -Infinite Queries can be prefetched like regular Queries. Per default, only the first page of the Query will be prefetched and will be stored under the given QueryKey. If you want to prefetch more than one page, you can use the `pages` option. Read the [prefetching guide](../prefetching) for more information. +Infinite Queries can be prefetched like regular Queries. Per default, only the first page of the Query will be prefetched and will be stored under the given QueryKey. If you want to prefetch more than one page, you can use the `pages` option. Read the [prefetching guide](./prefetching) for more information. ### New `combine` option for `useQueries` -See the [useQueries docs](../../reference/useQueries#combine) for more details. +See the [useQueries docs](../reference/useQueries#combine) for more details. ### Experimental `fine grained storage persister` -See the [experimental_createPersister docs](../../../react/plugins/createPersister) for more details. +See the [experimental_createPersister docs](../plugins/createPersister) for more details. [//]: # 'FrameworkSpecificNewFeatures' ### Typesafe way to create Query Options -See the [TypeScript docs](../../typescript#typing-query-options) for more details. +See the [TypeScript docs](../typescript#typing-query-options) for more details. ### new hooks for suspense @@ -524,6 +524,6 @@ const { data: post } = useSuspenseQuery({ The experimental `suspense: boolean` flag on the query hooks has been removed. -You can read more about them in the [suspense docs](../suspense). +You can read more about them in the [suspense docs](./suspense). [//]: # 'FrameworkSpecificNewFeatures' diff --git a/docs/framework/react/guides/network-mode.md b/docs/framework/react/guides/network-mode.md index 094971806f..439304f44d 100644 --- a/docs/framework/react/guides/network-mode.md +++ b/docs/framework/react/guides/network-mode.md @@ -3,13 +3,13 @@ id: network-mode title: Network Mode --- -TanStack Query provides three different network modes to distinguish how [Queries](../queries) and [Mutations](../mutations) should behave if you have no network connection. This mode can be set for each Query / Mutation individually, or globally via the query / mutation defaults. +TanStack Query provides three different network modes to distinguish how [Queries](./queries) and [Mutations](./mutations) should behave if you have no network connection. This mode can be set for each Query / Mutation individually, or globally via the query / mutation defaults. Since TanStack Query is most often used for data fetching in combination with data fetching libraries, the default network mode is [online](#network-mode-online). ## Network Mode: online -In this mode, Queries and Mutations will not fire unless you have network connection. This is the default mode. If a fetch is initiated for a query, it will always stay in the `state` (`pending`, `error`, `success`) it is in if the fetch cannot be made because there is no network connection. However, a [fetchStatus](../queries#fetchstatus) is exposed additionally. This can be either: +In this mode, Queries and Mutations will not fire unless you have network connection. This is the default mode. If a fetch is initiated for a query, it will always stay in the `state` (`pending`, `error`, `success`) it is in if the fetch cannot be made because there is no network connection. However, a [fetchStatus](./queries#fetchstatus) is exposed additionally. This can be either: - `fetching`: The `queryFn` is really executing - a request is in-flight. - `paused`: The query is not executing - it is `paused` until you have connection again @@ -19,7 +19,7 @@ The flags `isFetching` and `isPaused` are derived from this state and exposed fo > Keep in mind that it might not be enough to check for `pending` state to show a loading spinner. Queries can be in `state: 'pending'`, but `fetchStatus: 'paused'` if they are mounting for the first time, and you have no network connection. -If a query runs because you are online, but you go offline while the fetch is still happening, TanStack Query will also pause the retry mechanism. Paused queries will then continue to run once you re-gain network connection. This is independent of `refetchOnReconnect` (which also defaults to `true` in this mode), because it is not a `refetch`, but rather a `continue`. If the query has been [cancelled](../query-cancellation) in the meantime, it will not continue. +If a query runs because you are online, but you go offline while the fetch is still happening, TanStack Query will also pause the retry mechanism. Paused queries will then continue to run once you re-gain network connection. This is independent of `refetchOnReconnect` (which also defaults to `true` in this mode), because it is not a `refetch`, but rather a `continue`. If the query has been [cancelled](./query-cancellation) in the meantime, it will not continue. ## Network Mode: always @@ -37,7 +37,7 @@ In those situations, the first fetch might succeed because it comes from an offl ## Devtools -The [TanStack Query Devtools](../../devtools) will show Queries in a `paused` state if they would be fetching, but there is no network connection. There is also a toggle button to _Mock offline behavior_. Please note that this button will _not_ actually mess with your network connection (you can do that in the browser devtools), but it will set the [OnlineManager](../../../../reference/onlineManager) in an offline state. +The [TanStack Query Devtools](../devtools) will show Queries in a `paused` state if they would be fetching, but there is no network connection. There is also a toggle button to _Mock offline behavior_. Please note that this button will _not_ actually mess with your network connection (you can do that in the browser devtools), but it will set the [OnlineManager](../../../reference/onlineManager) in an offline state. ## Signature diff --git a/docs/framework/react/guides/prefetching.md b/docs/framework/react/guides/prefetching.md index ccdb5ce9df..060556a125 100644 --- a/docs/framework/react/guides/prefetching.md +++ b/docs/framework/react/guides/prefetching.md @@ -12,9 +12,9 @@ There are a few different prefetching patterns: 3. Via router integration 4. During Server Rendering (another form of router integration) -In this guide, we'll take a look at the first three, while the fourth will be covered in depth in the [Server Rendering & Hydration guide](../ssr) and the [Advanced Server Rendering guide](../advanced-ssr). +In this guide, we'll take a look at the first three, while the fourth will be covered in depth in the [Server Rendering & Hydration guide](./ssr) and the [Advanced Server Rendering guide](./advanced-ssr). -One specific use of prefetching is to avoid Request Waterfalls, for an in-depth background and explanation of those, see the [Performance & Request Waterfalls guide](../request-waterfalls). +One specific use of prefetching is to avoid Request Waterfalls, for an in-depth background and explanation of those, see the [Performance & Request Waterfalls guide](./request-waterfalls). ## prefetchQuery & prefetchInfiniteQuery @@ -196,7 +196,7 @@ This starts fetching `'article-comments'` immediately and flattens the waterfall [//]: # 'Suspense' -If you want to prefetch together with Suspense, you will have to do things a bit differently. You can't use `useSuspenseQueries` to prefetch, since the prefetch would block the component from rendering. You also can not use `useQuery` for the prefetch, because that wouldn't start the prefetch until after suspenseful query had resolved. For this scenario, you can use the [`usePrefetchQuery`](../../reference/usePrefetchQuery) or the [`usePrefetchInfiniteQuery`](../../reference/usePrefetchInfiniteQuery) hooks available in the library. +If you want to prefetch together with Suspense, you will have to do things a bit differently. You can't use `useSuspenseQueries` to prefetch, since the prefetch would block the component from rendering. You also can not use `useQuery` for the prefetch, because that wouldn't start the prefetch until after suspenseful query had resolved. For this scenario, you can use the [`usePrefetchQuery`](../reference/usePrefetchQuery) or the [`usePrefetchInfiniteQuery`](../reference/usePrefetchInfiniteQuery) hooks available in the library. You can now use `useSuspenseQuery` in the component that actually needs the data. You _might_ want to wrap this later component in its own `` boundary so the "secondary" query we are prefetching does not block rendering of the "primary" data. @@ -267,7 +267,7 @@ Let's look at a slightly more advanced case next. ### Dependent Queries & Code Splitting -Sometimes we want to prefetch conditionally, based on the result of another fetch. Consider this example borrowed from the [Performance & Request Waterfalls guide](../request-waterfalls): +Sometimes we want to prefetch conditionally, based on the result of another fetch. Consider this example borrowed from the [Performance & Request Waterfalls guide](./request-waterfalls): [//]: # 'ExampleConditionally1' @@ -367,7 +367,7 @@ There is a tradeoff however, in that the code for `getGraphDataById` is now incl Because data fetching in the component tree itself can easily lead to request waterfalls and the different fixes for that can be cumbersome as they accumulate throughout the application, an attractive way to do prefetching is integrating it at the router level. -In this approach, you explicitly declare for each _route_ what data is going to be needed for that component tree, ahead of time. Because Server Rendering has traditionally needed all data to be loaded before rendering starts, this has been the dominating approach for SSR'd apps for a long time. This is still a common approach and you can read more about it in the [Server Rendering & Hydration guide](../ssr). +In this approach, you explicitly declare for each _route_ what data is going to be needed for that component tree, ahead of time. Because Server Rendering has traditionally needed all data to be loaded before rendering starts, this has been the dominating approach for SSR'd apps for a long time. This is still a common approach and you can read more about it in the [Server Rendering & Hydration guide](./ssr). For now, let's focus on the client side case and look at an example of how you can make this work with [Tanstack Router](https://tanstack.com/router). These examples leave out a lot of setup and boilerplate to stay concise, you can check out a [full React Query example](https://tanstack.com/router/v1/docs/framework/react/examples/basic-react-query-file-based) over in the [Tanstack Router docs](https://tanstack.com/router/v1/docs). @@ -418,7 +418,7 @@ Integration with other routers is also possible, see the [React Router example]( ## Manually Priming a Query -If you already have the data for your query synchronously available, you don't need to prefetch it. You can just use the [Query Client's `setQueryData` method](../../../../reference/QueryClient/#queryclientsetquerydata) to directly add or update a query's cached result by key. +If you already have the data for your query synchronously available, you don't need to prefetch it. You can just use the [Query Client's `setQueryData` method](../../../reference/QueryClient#queryclientsetquerydata) to directly add or update a query's cached result by key. [//]: # 'ExampleManualPriming' @@ -433,6 +433,6 @@ queryClient.setQueryData(['todos'], todos) For a deep-dive on how to get data into your Query Cache before you fetch, have a look at [#17: Seeding the Query Cache](../community/tkdodos-blog#17-seeding-the-query-cache) from the Community Resources. -Integrating with Server Side routers and frameworks is very similar to what we just saw, with the addition that the data has to passed from the server to the client to be hydrated into the cache there. To learn how, continue on to the [Server Rendering & Hydration guide](../ssr). +Integrating with Server Side routers and frameworks is very similar to what we just saw, with the addition that the data has to passed from the server to the client to be hydrated into the cache there. To learn how, continue on to the [Server Rendering & Hydration guide](./ssr). [//]: # 'Materials' diff --git a/docs/framework/react/guides/queries.md b/docs/framework/react/guides/queries.md index bde7dbe2fe..25867251a0 100644 --- a/docs/framework/react/guides/queries.md +++ b/docs/framework/react/guides/queries.md @@ -5,7 +5,7 @@ title: Queries ## Query Basics -A query is a declarative dependency on an asynchronous source of data that is tied to a **unique key**. A query can be used with any Promise based method (including GET and POST methods) to fetch data from a server. If your method modifies data on the server, we recommend using [Mutations](../mutations) instead. +A query is a declarative dependency on an asynchronous source of data that is tied to a **unique key**. A query can be used with any Promise based method (including GET and POST methods) to fetch data from a server. If your method modifies data on the server, we recommend using [Mutations](./mutations) instead. To subscribe to a query in your components or custom hooks, call the `useQuery` hook with at least: diff --git a/docs/framework/react/guides/query-functions.md b/docs/framework/react/guides/query-functions.md index 4b3cffe871..0b20bebaba 100644 --- a/docs/framework/react/guides/query-functions.md +++ b/docs/framework/react/guides/query-functions.md @@ -99,15 +99,15 @@ function fetchTodoList({ queryKey }) { The `QueryFunctionContext` is the object passed to each query function. It consists of: -- `queryKey: QueryKey`: [Query Keys](../query-keys) -- `client: QueryClient`: [QueryClient](../../../../reference/QueryClient) +- `queryKey: QueryKey`: [Query Keys](./query-keys) +- `client: QueryClient`: [QueryClient](../../../reference/QueryClient) - `signal?: AbortSignal` - [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance provided by TanStack Query - - Can be used for [Query Cancellation](../query-cancellation) + - Can be used for [Query Cancellation](./query-cancellation) - `meta: Record | undefined` - an optional field you can fill with additional information about your query -Additionally, [Infinite Queries](../infinite-queries) get the following options passed: +Additionally, [Infinite Queries](./infinite-queries) get the following options passed: - `pageParam: TPageParam` - the page parameter used to fetch the current page diff --git a/docs/framework/react/guides/query-invalidation.md b/docs/framework/react/guides/query-invalidation.md index 9765885503..eeb7451ca1 100644 --- a/docs/framework/react/guides/query-invalidation.md +++ b/docs/framework/react/guides/query-invalidation.md @@ -25,7 +25,7 @@ When a query is invalidated with `invalidateQueries`, two things happen: ## Query Matching with `invalidateQueries` -When using APIs like `invalidateQueries` and `removeQueries` (and others that support partial query matching), you can match multiple queries by their prefix, or get really specific and match an exact query. For information on the types of filters you can use, please see [Query Filters](../filters#query-filters). +When using APIs like `invalidateQueries` and `removeQueries` (and others that support partial query matching), you can match multiple queries by their prefix, or get really specific and match an exact query. For information on the types of filters you can use, please see [Query Filters](./filters#query-filters). In this example, we can use the `todos` prefix to invalidate any queries that start with `todos` in their query key: diff --git a/docs/framework/react/guides/request-waterfalls.md b/docs/framework/react/guides/request-waterfalls.md index 9d9b1a0409..35ebfd9a27 100644 --- a/docs/framework/react/guides/request-waterfalls.md +++ b/docs/framework/react/guides/request-waterfalls.md @@ -7,11 +7,11 @@ Application performance is a broad and complex area and while React Query can't The biggest performance footgun when using React Query, or indeed any data fetching library that lets you fetch data inside of components, is request waterfalls. The rest of this page will explain what they are, how you can spot them and how you can restructure your application or APIs to avoid them. -The [Prefetching & Router Integration guide](../prefetching) builds on this and teaches you how to prefetch data ahead of time when it's not possible or feasible to restructure your application or APIs. +The [Prefetching & Router Integration guide](./prefetching) builds on this and teaches you how to prefetch data ahead of time when it's not possible or feasible to restructure your application or APIs. -The [Server Rendering & Hydration guide](../ssr) teaches you how to prefetch data on the server and pass that data down to the client so you don't have to fetch it again. +The [Server Rendering & Hydration guide](./ssr) teaches you how to prefetch data on the server and pass that data down to the client so you don't have to fetch it again. -The [Advanced Server Rendering guide](../advanced-ssr) further teaches you how to apply these patterns to Server Components and Streaming Server Rendering. +The [Advanced Server Rendering guide](./advanced-ssr) further teaches you how to apply these patterns to Server Components and Streaming Server Rendering. ## What is a Request Waterfall? @@ -65,7 +65,7 @@ With this as a basis, let's look at a few different patterns that can lead to Re ### Single Component Waterfalls / Serial Queries -When a single component first fetches one query, and then another, that's a request waterfall. This can happen when the second query is a [Dependent Query](../dependent-queries), that is, it depends on data from the first query when fetching: +When a single component first fetches one query, and then another, that's a request waterfall. This can happen when the second query is a [Dependent Query](./dependent-queries), that is, it depends on data from the first query when fetching: ```tsx // Get the user @@ -195,7 +195,7 @@ function Article({ id }) { The two queries will now fetch in parallel. Note that if you are using suspense, you'd want to combine these two queries into a single `useSuspenseQueries` instead. -Another way to flatten this waterfall would be to prefetch the comments in the `
` component, or prefetch both of these queries at the router level on page load or page navigation, read more about this in the [Prefetching & Router Integration guide](../prefetching). +Another way to flatten this waterfall would be to prefetch the comments in the `
` component, or prefetch both of these queries at the router level on page load or page navigation, read more about this in the [Prefetching & Router Integration guide](./prefetching). Next, let's look at a _Dependent Nested Component Waterfall_. @@ -240,7 +240,7 @@ The second query `getGraphDataById` is dependent on it's parent in two different 2. |> getGraphDataById() ``` -In this example, we can't trivially flatten the waterfall by just hoisting the query to the parent, or even adding prefetching. Just like the dependent query example at the beginning of this guide, one option is to refactor our API to include the graph data in the `getFeed` query. Another more advanced solution is to leverage Server Components to move the waterfall to the server where latency is lower (read more about this in the [Advanced Server Rendering guide](../advanced-ssr)) but note that this can be a very big architectural change. +In this example, we can't trivially flatten the waterfall by just hoisting the query to the parent, or even adding prefetching. Just like the dependent query example at the beginning of this guide, one option is to refactor our API to include the graph data in the `getFeed` query. Another more advanced solution is to leverage Server Components to move the waterfall to the server where latency is lower (read more about this in the [Advanced Server Rendering guide](./advanced-ssr)) but note that this can be a very big architectural change. You can have good performance even with a few query waterfalls here and there, just know they are a common performance concern and be mindful about them. An especially insidious version is when Code Splitting is involved, let's take a look at this next. @@ -307,7 +307,7 @@ But that's just looking at the code from the example, if we consider what the fi 5. |> getGraphDataById() ``` -Note that this looks a bit different when server rendering, we will explore that further in the [Server Rendering & Hydration guide](../ssr). Also note that it's not uncommon for the route that contains `` to also be code split, which could add yet another hop. +Note that this looks a bit different when server rendering, we will explore that further in the [Server Rendering & Hydration guide](./ssr). Also note that it's not uncommon for the route that contains `` to also be code split, which could add yet another hop. In the code split case, it might actually help to hoist the `getGraphDataById` query to the `` component and make it conditional, or add a conditional prefetch. That query could then be fetched in parallel with the code, turning the example part into this: @@ -317,7 +317,7 @@ In the code split case, it might actually help to hoist the `getGraphDataById` q 2. |> JS for ``` -This is very much a tradeoff however. You are now including the data fetching code for `getGraphDataById` in the same bundle as ``, so evaluate what is best for your case. Read more about how to do this in the [Prefetching & Router Integration guide](../prefetching). +This is very much a tradeoff however. You are now including the data fetching code for `getGraphDataById` in the same bundle as ``, so evaluate what is best for your case. Read more about how to do this in the [Prefetching & Router Integration guide](./prefetching). > The tradeoff between: > @@ -337,4 +337,4 @@ Request Waterfalls are a very common and complex performance concern with many t Because of this accidental complexity, it pays off to be mindful of waterfalls and regularly examine your application looking for them (a good way is to examine the Network tab every now and then!). You don't necessarily have to flatten them all to have good performance, but keep an eye out for the high impact ones. -In the next guide, we'll look at more ways to flatten waterfalls, by leveraging [Prefetching & Router Integration](../prefetching). +In the next guide, we'll look at more ways to flatten waterfalls, by leveraging [Prefetching & Router Integration](./prefetching). diff --git a/docs/framework/react/guides/ssr.md b/docs/framework/react/guides/ssr.md index 6c522c5916..290193d6a9 100644 --- a/docs/framework/react/guides/ssr.md +++ b/docs/framework/react/guides/ssr.md @@ -5,9 +5,9 @@ title: Server Rendering & Hydration In this guide you'll learn how to use React Query with server rendering. -See the guide on [Prefetching & Router Integration](../prefetching) for some background. You might also want to check out the [Performance & Request Waterfalls guide](../request-waterfalls) before that. +See the guide on [Prefetching & Router Integration](./prefetching) for some background. You might also want to check out the [Performance & Request Waterfalls guide](./request-waterfalls) before that. -For advanced server rendering patterns, such as streaming, Server Components and the new Next.js app router, see the [Advanced Server Rendering guide](../advanced-ssr). +For advanced server rendering patterns, such as streaming, Server Components and the new Next.js app router, see the [Advanced Server Rendering guide](./advanced-ssr). If you just want to see some code, you can skip ahead to the [Full Next.js pages router example](#full-nextjs-pages-router-example) or the [Full Remix example](#full-remix-example) below. @@ -386,7 +386,7 @@ With Remix, this is a little bit more involved, we recommend checking out the [u ## Prefetching dependent queries -Over in the Prefetching guide we learned how to [prefetch dependent queries](../prefetching#dependent-queries--code-splitting), but how do we do this in framework loaders? Consider the following code, taken from the [Dependent Queries guide](../dependent-queries): +Over in the Prefetching guide we learned how to [prefetch dependent queries](./prefetching#dependent-queries--code-splitting), but how do we do this in framework loaders? Consider the following code, taken from the [Dependent Queries guide](./dependent-queries): ```tsx // Get the user @@ -482,7 +482,7 @@ If you are using a custom SSR setup, you need to take care of this step yourself ## A note about request waterfalls -In the [Performance & Request Waterfalls guide](../request-waterfalls) we mentioned we would revisit how server rendering changes one of the more complex nested waterfalls. Check back for the [specific code example](../request-waterfalls#code-splitting), but as a refresher, we have a code split `` component inside a `` component. This only renders if the feed contains a graph item and both of these components fetches their own data. With client rendering, this leads to the following request waterfall: +In the [Performance & Request Waterfalls guide](./request-waterfalls) we mentioned we would revisit how server rendering changes one of the more complex nested waterfalls. Check back for the [specific code example](./request-waterfalls#code-splitting), but as a refresher, we have a code split `` component inside a `` component. This only renders if the feed contains a graph item and both of these components fetches their own data. With client rendering, this leads to the following request waterfall: ``` 1. |> Markup (without content) @@ -528,7 +528,7 @@ Modern frameworks often try to solve this by fetching the initial code and data 2. |> JS for ``` -This is much better, but if we want to improve this further we can flatten this to a single roundtrip with Server Components. Learn how in the [Advanced Server Rendering guide](../advanced-ssr). +This is much better, but if we want to improve this further we can flatten this to a single roundtrip with Server Components. Learn how in the [Advanced Server Rendering guide](./advanced-ssr). ## Tips, Tricks and Caveats @@ -546,9 +546,9 @@ In case you are creating the `QueryClient` for every request, React Query create On the server, `gcTime` defaults to `Infinity` which disables manual garbage collection and will automatically clear memory once a request has finished. If you are explicitly setting a non-Infinity `gcTime` then you will be responsible for clearing the cache early. -Avoid setting `gcTime` to `0` as it may result in a hydration error. This occurs because the [Hydration Boundary](../../reference/hydration#hydrationboundary) places necessary data into the cache for rendering, but if the garbage collector removes the data before the rendering completes, issues may arise. If you require a shorter `gcTime`, we recommend setting it to `2 * 1000` to allow sufficient time for the app to reference the data. +Avoid setting `gcTime` to `0` as it may result in a hydration error. This occurs because the [Hydration Boundary](../reference/hydration#hydrationboundary) places necessary data into the cache for rendering, but if the garbage collector removes the data before the rendering completes, issues may arise. If you require a shorter `gcTime`, we recommend setting it to `2 * 1000` to allow sufficient time for the app to reference the data. -To clear the cache after it is not needed and to lower memory consumption, you can add a call to [`queryClient.clear()`](../../../../reference/QueryClient/#queryclientclear) after the request is handled and dehydrated state has been sent to the client. +To clear the cache after it is not needed and to lower memory consumption, you can add a call to [`queryClient.clear()`](../../../reference/QueryClient#queryclientclear) after the request is handled and dehydrated state has been sent to the client. Alternatively, you can set a smaller `gcTime`. diff --git a/docs/framework/react/guides/suspense.md b/docs/framework/react/guides/suspense.md index 31fac80357..3bada93cbc 100644 --- a/docs/framework/react/guides/suspense.md +++ b/docs/framework/react/guides/suspense.md @@ -5,9 +5,9 @@ title: Suspense React Query can also be used with React's Suspense for Data Fetching API's. For this, we have dedicated hooks: -- [useSuspenseQuery](../../reference/useSuspenseQuery) -- [useSuspenseInfiniteQuery](../../reference/useSuspenseInfiniteQuery) -- [useSuspenseQueries](../../reference/useSuspenseQueries) +- [useSuspenseQuery](../reference/useSuspenseQuery) +- [useSuspenseInfiniteQuery](../reference/useSuspenseInfiniteQuery) +- [useSuspenseQueries](../reference/useSuspenseQueries) - Additionally, you can use the `useQuery().promise` and `React.use()` (Experimental) When using suspense mode, `status` states and `error` objects are not needed and are then replaced by usage of the `React.Suspense` component (including the use of the `fallback` prop and React error boundaries for catching errors). Please read the [Resetting Error Boundaries](#resetting-error-boundaries) and look at the [Suspense Example](https://stackblitz.com/github/TanStack/query/tree/main/examples/react/suspense) for more information on how to set up suspense mode. @@ -107,7 +107,7 @@ const App = () => { ## Fetch-on-render vs Render-as-you-fetch -Out of the box, React Query in `suspense` mode works really well as a **Fetch-on-render** solution with no additional configuration. This means that when your components attempt to mount, they will trigger query fetching and suspend, but only once you have imported them and mounted them. If you want to take it to the next level and implement a **Render-as-you-fetch** model, we recommend implementing [Prefetching](../prefetching) on routing callbacks and/or user interactions events to start loading queries before they are mounted and hopefully even before you start importing or mounting their parent components. +Out of the box, React Query in `suspense` mode works really well as a **Fetch-on-render** solution with no additional configuration. This means that when your components attempt to mount, they will trigger query fetching and suspend, but only once you have imported them and mounted them. If you want to take it to the next level and implement a **Render-as-you-fetch** model, we recommend implementing [Prefetching](./prefetching) on routing callbacks and/or user interactions events to start loading queries before they are mounted and hopefully even before you start importing or mounting their parent components. ## Suspense on the Server with streaming @@ -172,7 +172,7 @@ export function Providers(props: { children: React.ReactNode }) { } ``` -For more information, check out the [NextJs Suspense Streaming Example](../../examples/nextjs-suspense-streaming) and the [Advanced Rendering & Hydration](../advanced-ssr) guide. +For more information, check out the [NextJs Suspense Streaming Example](../../examples/nextjs-suspense-streaming) and the [Advanced Rendering & Hydration](./advanced-ssr) guide. ## Using `useQuery().promise` and `React.use()` (Experimental) diff --git a/docs/framework/react/guides/updates-from-mutation-responses.md b/docs/framework/react/guides/updates-from-mutation-responses.md index be5af9b611..a78876f580 100644 --- a/docs/framework/react/guides/updates-from-mutation-responses.md +++ b/docs/framework/react/guides/updates-from-mutation-responses.md @@ -3,7 +3,7 @@ id: updates-from-mutation-responses title: Updates from Mutation Responses --- -When dealing with mutations that **update** objects on the server, it's common for the new object to be automatically returned in the response of the mutation. Instead of refetching any queries for that item and wasting a network call for data we already have, we can take advantage of the object returned by the mutation function and update the existing query with the new data immediately using the [Query Client's `setQueryData`](../../../../reference/QueryClient/#queryclientsetquerydata) method: +When dealing with mutations that **update** objects on the server, it's common for the new object to be automatically returned in the response of the mutation. Instead of refetching any queries for that item and wasting a network call for data we already have, we can take advantage of the object returned by the mutation function and update the existing query with the new data immediately using the [Query Client's `setQueryData`](../../../reference/QueryClient#queryclientsetquerydata) method: [//]: # 'Example'