From 0fa4073c89bda8c72147f3b5164aa8641ea2ba37 Mon Sep 17 00:00:00 2001 From: Lachlan Collins <1667261+lachlancollins@users.noreply.github.com> Date: Fri, 26 Jan 2024 19:53:03 +1100 Subject: [PATCH] docs: Fix relative link depth --- docs/framework/angular/guides/caching.md | 4 +-- .../guides/invalidations-from-mutations.md | 2 +- docs/framework/angular/installation.md | 2 +- docs/framework/angular/overview.md | 2 +- docs/framework/angular/quick-start.md | 2 +- docs/framework/react/guides/advanced-ssr.md | 8 ++--- docs/framework/react/guides/caching.md | 4 +-- .../react/guides/dependent-queries.md | 2 +- .../react/guides/important-defaults.md | 4 +-- .../react/guides/initial-query-data.md | 6 ++-- .../guides/invalidations-from-mutations.md | 2 +- .../guides/migrating-to-react-query-3.md | 4 +-- .../guides/migrating-to-react-query-4.md | 26 +++++++------- .../framework/react/guides/migrating-to-v5.md | 16 ++++----- docs/framework/react/guides/mutations.md | 10 +++--- docs/framework/react/guides/network-mode.md | 8 ++--- .../react/guides/placeholder-query-data.md | 6 ++-- docs/framework/react/guides/prefetching.md | 16 ++++----- docs/framework/react/guides/queries.md | 6 ++-- .../framework/react/guides/query-functions.md | 6 ++-- .../react/guides/query-invalidation.md | 2 +- docs/framework/react/guides/query-keys.md | 4 +-- docs/framework/react/guides/query-options.md | 2 +- .../react/guides/request-waterfalls.md | 22 ++++++------ docs/framework/react/guides/ssr.md | 18 +++++----- docs/framework/react/guides/suspense.md | 10 +++--- docs/framework/react/guides/testing.md | 2 +- .../guides/updates-from-mutation-responses.md | 2 +- .../plugins/createAsyncStoragePersister.md | 4 +-- .../plugins/createSyncStoragePersister.md | 2 +- .../react/plugins/persistQueryClient.md | 14 ++++---- .../react/reference/infiniteQueryOptions.md | 2 +- .../framework/react/reference/queryOptions.md | 2 +- .../react/reference/useInfiniteQuery.md | 8 ++--- .../react/reference/useIsFetching.md | 2 +- .../react/reference/useIsMutating.md | 2 +- docs/framework/react/reference/useMutation.md | 4 +-- .../react/reference/useMutationState.md | 2 +- docs/framework/react/reference/useQueries.md | 2 +- docs/framework/react/reference/useQuery.md | 12 +++---- .../reference/useSuspenseInfiniteQuery.md | 4 +-- .../react/reference/useSuspenseQueries.md | 4 +-- .../react/reference/useSuspenseQuery.md | 4 +-- docs/framework/svelte/installation.md | 2 +- docs/framework/svelte/ssr.md | 2 +- docs/framework/vue/guides/ssr.md | 2 +- docs/framework/vue/guides/suspense.md | 2 +- docs/framework/vue/installation.md | 2 +- docs/framework/vue/overview.md | 2 +- docs/framework/vue/quick-start.md | 2 +- docs/reference/InfiniteQueryObserver.md | 2 +- docs/reference/QueriesObserver.md | 2 +- docs/reference/QueryCache.md | 10 +++--- docs/reference/QueryClient.md | 34 +++++++++---------- docs/reference/QueryObserver.md | 2 +- 55 files changed, 165 insertions(+), 165 deletions(-) diff --git a/docs/framework/angular/guides/caching.md b/docs/framework/angular/guides/caching.md index d8bae54146e..f4540f2f7d3 100644 --- a/docs/framework/angular/guides/caching.md +++ b/docs/framework/angular/guides/caching.md @@ -3,7 +3,7 @@ id: caching title: Caching Examples --- -> Please thoroughly read the [Important Defaults](../guides/important-defaults) before reading this guide +> Please thoroughly read the [Important Defaults](./guides/important-defaults) before reading this guide ## Basic Example @@ -23,7 +23,7 @@ Let's assume we are using the default `gcTime` of **5 minutes** and the default - A second instance of `injectQuery(() => ({ queryKey: ['todos'], queryFn: fetchTodos })` initializes elsewhere. - Since the cache already has data for the `['todos']` key from the first query, that data is immediately returned from the cache. - The new instance triggers a new network request using its query function. - - Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](../reference/injectQuery) are updated (including `isFetching`, `isPending`, and other related values) because they have the same query key. + - Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](./reference/injectQuery) are updated (including `isFetching`, `isPending`, and other related values) because they have the same query key. - When the request completes successfully, the cache's data under the `['todos']` key is updated with the new data, and both instances are updated with the new data. - Both instances of the `injectQuery(() => ({ queryKey: ['todos'], queryFn: fetchTodos })` query are destroyed and no longer in use. - Since there are no more active instances of this query, a garbage collection timeout is set using `gcTime` to delete and garbage collect the query (defaults to **5 minutes**). diff --git a/docs/framework/angular/guides/invalidations-from-mutations.md b/docs/framework/angular/guides/invalidations-from-mutations.md index 9e1e6e0a657..5d72339af8f 100644 --- a/docs/framework/angular/guides/invalidations-from-mutations.md +++ b/docs/framework/angular/guides/invalidations-from-mutations.md @@ -40,4 +40,4 @@ export class TodosComponent { [//]: # 'Example2' -You can wire up your invalidations to happen using any of the callbacks available in the [`injectMutation` function](../guides/mutations) +You can wire up your invalidations to happen using any of the callbacks available in the [`injectMutation` function](./guides/mutations) diff --git a/docs/framework/angular/installation.md b/docs/framework/angular/installation.md index e9316d187f9..de785bb89d8 100644 --- a/docs/framework/angular/installation.md +++ b/docs/framework/angular/installation.md @@ -17,4 +17,4 @@ $ pnpm add @tanstack/angular-query-experimental $ yarn add @tanstack/angular-query-experimental ``` -> Wanna give it a spin before you download? Try out the [simple](../examples/angular/simple) or [basic](../examples/angular/basic) examples! +> Wanna give it a spin before you download? Try out the [simple](./examples/simple) or [basic](./examples/basic) examples! diff --git a/docs/framework/angular/overview.md b/docs/framework/angular/overview.md index 50a9c4746e9..346f11b0d24 100644 --- a/docs/framework/angular/overview.md +++ b/docs/framework/angular/overview.md @@ -114,4 +114,4 @@ type Response = { ## You talked me into it, so what now? -- Learn Angular Query at your own pace with our amazingly thorough [Walkthrough Guide](../installation) and [API Reference](../reference/injectQuery) +- Learn Angular Query at your own pace with our amazingly thorough [Walkthrough Guide](./installation) and [API Reference](./reference/injectQuery) diff --git a/docs/framework/angular/quick-start.md b/docs/framework/angular/quick-start.md index c8fe325bc1d..d31a97e65de 100644 --- a/docs/framework/angular/quick-start.md +++ b/docs/framework/angular/quick-start.md @@ -7,7 +7,7 @@ title: Quick Start [//]: # 'Example' -If you're looking for a fully functioning example, please have a look at our [basic codesandbox example](../examples/angular/basic) +If you're looking for a fully functioning example, please have a look at our [basic codesandbox example](./examples/basic) ### Provide the client to your App diff --git a/docs/framework/react/guides/advanced-ssr.md b/docs/framework/react/guides/advanced-ssr.md index 21ec001678b..a8a32aea7c2 100644 --- a/docs/framework/react/guides/advanced-ssr.md +++ b/docs/framework/react/guides/advanced-ssr.md @@ -5,7 +5,7 @@ title: Advanced Server Rendering Welcome to the Advanced Server Rendering guide, where you will learn all about using React Query with streaming, Server Components and the Next.js app router. -You might want to read the [Server Rendering & Hydration guide](../guides/ssr) before this one as it teaches the basics for using React Query with SSR, and [Performance & Request Waterfalls](../guides/request-waterfalls) as well as [Prefetching & Router Integration](../guides/prefetching) also contains valuable background. +You might want to read the [Server Rendering & Hydration guide](./guides/ssr) before this one as it teaches the basics for using React Query with SSR, and [Performance & Request Waterfalls](./guides/request-waterfalls) as well as [Prefetching & Router Integration](./guides/prefetching) also contains valuable background. Before we start, let's note that while the `initialData` approach outlined in the SSR guide also works with Server Components, we'll focus this guide on the hydration APIs. @@ -13,7 +13,7 @@ Before we start, let's note that while the `initialData` approach outlined in th We won't cover Server Components in depth here, but the short version is that they are components that are guaranteed to _only_ run on the server, both for the initial page view and **also on page transitions**. This is similar to how Next.js `getServerSideProps`/`getStaticProps` and Remix `loader` works, as these also always run on the server but while those can only return data, Server Components can do a lot more. The data part is central to React Query however, so let's focus on that. -How do we take what we learned in the Server Rendering guide about [passing data prefetched in framework loaders to the app](../guides/ssr#using-the-hydration-apis) and apply that to Server Components and the Next.js app router? The best way to start thinking about this is to consider Server Components as "just" another framework loader. +How do we take what we learned in the Server Rendering guide about [passing data prefetched in framework loaders to the app](./guides/ssr#using-the-hydration-apis) and apply that to Server Components and the Next.js app router? The best way to start thinking about this is to consider Server Components as "just" another framework loader. ### A quick note on terminology @@ -363,11 +363,11 @@ export function Providers(props: { children: React.ReactNode }) { } ``` -For more information, check out the [NextJs Suspense Streaming Example](../examples/nextjs-suspense-streaming). +For more information, check out the [NextJs Suspense Streaming Example](./examples/nextjs-suspense-streaming). The big upside is that you no longer need to prefetch queries manually to have SSR work, and it even still streams in the result! This gives you phenomenal DX and lower code complexity. -The downside is easiest to explain if we look back at [the complex request waterfall example](../guides/request-waterfalls#code-splitting) in the Performance & Request Waterfalls guide. Server Components with prefetching effectively eliminates the request waterfalls both for the initial page load **and** any subsequent navigation. This prefetch-less approach however will only flatten the waterfalls on the initial page load but ends up the same deep waterfall as the original example on page navigations: +The downside is easiest to explain if we look back at [the complex request waterfall example](./guides/request-waterfalls#code-splitting) in the Performance & Request Waterfalls guide. Server Components with prefetching effectively eliminates the request waterfalls both for the initial page load **and** any subsequent navigation. This prefetch-less approach however will only flatten the waterfalls on the initial page load but ends up the same deep waterfall as the original example on page navigations: ``` 1. |> JS for diff --git a/docs/framework/react/guides/caching.md b/docs/framework/react/guides/caching.md index 3395f3aff8a..85e257e0a71 100644 --- a/docs/framework/react/guides/caching.md +++ b/docs/framework/react/guides/caching.md @@ -3,7 +3,7 @@ id: caching title: Caching Examples --- -> Please thoroughly read the [Important Defaults](../guides/important-defaults) before reading this guide +> Please thoroughly read the [Important Defaults](./guides/important-defaults) before reading this guide ## Basic Example @@ -23,7 +23,7 @@ Let's assume we are using the default `gcTime` of **5 minutes** and the default - A second instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts elsewhere. - Since the cache already has data for the `['todos']` key from the first query, that data is immediately returned from the cache. - The new instance triggers a new network request using its query function. - - Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](../reference/useQuery) are updated (including `isFetching`, `isPending`, and other related values) because they have the same query key. + - Note that regardless of whether both `fetchTodos` query functions are identical or not, both queries' [`status`](./reference/useQuery) are updated (including `isFetching`, `isPending`, and other related values) because they have the same query key. - When the request completes successfully, the cache's data under the `['todos']` key is updated with the new data, and both instances are updated with the new data. - Both instances of the `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` query are unmounted and no longer in use. - Since there are no more active instances of this query, a garbage collection timeout is set using `gcTime` to delete and garbage collect the query (defaults to **5 minutes**). diff --git a/docs/framework/react/guides/dependent-queries.md b/docs/framework/react/guides/dependent-queries.md index 0657258a86a..ffe1e0d389b 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](../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](./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. 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/important-defaults.md b/docs/framework/react/guides/important-defaults.md index d2f78d68e0b..0cbb0f47df1 100644 --- a/docs/framework/react/guides/important-defaults.md +++ b/docs/framework/react/guides/important-defaults.md @@ -36,7 +36,7 @@ Out of the box, TanStack Query is configured with **aggressive but sane** defaul Have a look at the following articles from our Community Resources for further explanations of the defaults: -- [Practical React Query](../community/tkdodos-blog#1-practical-react-query) -- [React Query as a State Manager](../community/tkdodos-blog#10-react-query-as-a-state-manager) +- [Practical React Query](./community/tkdodos-blog#1-practical-react-query) +- [React Query as a State Manager](./community/tkdodos-blog#10-react-query-as-a-state-manager) [//]: # 'Materials' diff --git a/docs/framework/react/guides/initial-query-data.md b/docs/framework/react/guides/initial-query-data.md index 4a24c50727f..c8993058828 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`](../guides/prefetching) - - [Manually place the data into the cache using `queryClient.setQueryData`](../guides/prefetching) + - [Prefetch the data using `queryClient.prefetchQuery`](./guides/prefetching) + - [Manually place the data into the cache using `queryClient.setQueryData`](./guides/prefetching) ## Using `initialData` to prepopulate a query @@ -170,6 +170,6 @@ const result = useQuery({ ## Further reading -For a comparison between `Initial Data` and `Placeholder Data`, have a look at the [Community Resources](../community/tkdodos-blog#9-placeholder-and-initial-data-in-react-query). +For a comparison between `Initial Data` and `Placeholder Data`, have a look at the [Community Resources](./community/tkdodos-blog#9-placeholder-and-initial-data-in-react-query). [//]: # 'Materials' diff --git a/docs/framework/react/guides/invalidations-from-mutations.md b/docs/framework/react/guides/invalidations-from-mutations.md index 2f3352e2d30..b7d155ea2ce 100644 --- a/docs/framework/react/guides/invalidations-from-mutations.md +++ b/docs/framework/react/guides/invalidations-from-mutations.md @@ -36,4 +36,4 @@ const mutation = useMutation({ [//]: # 'Example2' -You can wire up your invalidations to happen using any of the callbacks available in the [`useMutation` hook](../guides/mutations) +You can wire up your invalidations to happen using any of the callbacks available in the [`useMutation` hook](./guides/mutations) 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 aed7f6aa06c..0fe7dded3dc 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 38779170afb..1a078e0a0bd 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](../guides/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](./guides/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](../guides/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](./guides/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](../guides/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](../guides/queries#why-two-different-states). +With the introduction of the new [fetchStatus](./guides/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](./guides/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' ``` -Also, have a look at [the guide on dependent queries](../guides/dependent-queries) +Also, have a look at [the guide on dependent queries](./guides/dependent-queries) #### disabled queries @@ -121,7 +121,7 @@ Due to this change, disabled queries (even temporarily disabled ones) will start + isInitialLoading ``` -See also the guide on [disabling queries](../guides/disabling-queries#isInitialLoading) +See also the guide on [disabling queries](./guides/disabling-queries#isInitialLoading) ### new API for `useQueries` @@ -148,7 +148,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](../guides/network-mode) +Please read the [New Features announcement](#proper-offline-support) about online / offline support, and also the dedicated page about [Network mode](./guides/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: @@ -209,7 +209,7 @@ queryClient.refetchQueries({ queryKey: ['todos'] }, { cancelRefetch: false }) ### Query Filters -A [query filter](../guides/filters) is an object with certain conditions to match a query. Historically, the filter options have mostly been a combination of boolean flags. However, combining those flags can lead to impossible states. Specifically: +A [query filter](./guides/filters) is an object with certain conditions to match a query. Historically, the filter options have mostly been a combination of boolean flags. However, combining those flags can lead to impossible states. Specifically: ``` active?: boolean @@ -234,7 +234,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 @@ -272,7 +272,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: @@ -288,7 +288,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](../guides/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](../guides/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](./guides/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](./guides/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 @@ -296,7 +296,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 @@ -411,7 +411,7 @@ In v3, React Query has always fired off queries and mutations, but then taken th - You are offline and want to fire off a query that doesn't necessarily need network connection (because you _can_ use React Query for something other than data fetching), but it fails for some other reason. That query will now be paused until you go online again. - Window focus refetching didn't do anything at all if you were offline. -With v4, React Query introduces a new `networkMode` to tackle all these issues. Please read the dedicated page about the new [Network mode](../guides/network-mode) for more information. +With v4, React Query introduces a new `networkMode` to tackle all these issues. Please read the dedicated page about the new [Network mode](./guides/network-mode) for more information. ### Tracked Queries per default @@ -419,7 +419,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 4edad698671..a3a62afca2c 100644 --- a/docs/framework/react/guides/migrating-to-v5.md +++ b/docs/framework/react/guides/migrating-to-v5.md @@ -186,7 +186,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 @@ -235,7 +235,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 @@ -470,7 +470,7 @@ if (queryInfo.data) { } ``` -Here, we are only changing how the UI looks when the mutation is running instead of writing data directly to the cache. This works best if we only have one place where we need to show the optimistic update. For more details, have a look at the [optimistic updates documentation](../guides/optimistic-updates). +Here, we are only changing how the UI looks when the mutation is running instead of writing data directly to the cache. This works best if we only have one place where we need to show the optimistic update. For more details, have a look at the [optimistic updates documentation](./guides/optimistic-updates). ### Limited, Infinite Queries with new maxPages option @@ -484,21 +484,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](../guides/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](./guides/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](../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 @@ -514,6 +514,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](../guides/suspense). +You can read more about them in the [suspense docs](./guides/suspense). [//]: # 'FrameworkSpecificNewFeatures' diff --git a/docs/framework/react/guides/mutations.md b/docs/framework/react/guides/mutations.md index f055a75c8ea..5d5ca3c91e4 100644 --- a/docs/framework/react/guides/mutations.md +++ b/docs/framework/react/guides/mutations.md @@ -59,7 +59,7 @@ Beyond those primary states, more information is available depending on the stat In the example above, you also saw that you can pass variables to your mutations function by calling the `mutate` function with a **single variable or object**. -Even with just variables, mutations aren't all that special, but when used with the `onSuccess` option, the [Query Client's `invalidateQueries` method](../reference/QueryClient#queryclientinvalidatequeries) and the [Query Client's `setQueryData` method](../reference/QueryClient#queryclientsetquerydata), mutations become a very powerful tool. +Even with just variables, mutations aren't all that special, but when used with the `onSuccess` option, the [Query Client's `invalidateQueries` method](./reference/QueryClient#queryclientinvalidatequeries) and the [Query Client's `setQueryData` method](./reference/QueryClient#queryclientsetquerydata), mutations become a very powerful tool. [//]: # 'Info1' @@ -136,7 +136,7 @@ const CreateTodo = () => { ## Mutation Side Effects -`useMutation` comes with some helper options that allow quick and easy side-effects at any stage during the mutation lifecycle. These come in handy for both [invalidating and refetching queries after mutations](../guides/invalidations-from-mutations) and even [optimistic updates](../guides/optimistic-updates) +`useMutation` comes with some helper options that allow quick and easy side-effects at any stage during the mutation lifecycle. These come in handy for both [invalidating and refetching queries after mutations](./guides/invalidations-from-mutations) and even [optimistic updates](./guides/optimistic-updates) [//]: # 'Example4' @@ -343,7 +343,7 @@ queryClient.resumePausedMutations() ### Persisting Offline mutations -If you persist offline mutations with the [persistQueryClient plugin](../plugins/persistQueryClient), mutations cannot be resumed when the page is reloaded unless you provide a default mutation function. +If you persist offline mutations with the [persistQueryClient plugin](./plugins/persistQueryClient), mutations cannot be resumed when the page is reloaded unless you provide a default mutation function. This is a technical limitation. When persisting to an external storage, only the state of mutations is persisted, as functions cannot be serialized. After hydration, the component that triggers the mutation might not be mounted, so calling `resumePausedMutations` might yield an error: `No mutationFn found`. @@ -386,13 +386,13 @@ export default function App() { [//]: # 'Example11' -We also have an extensive [offline example](../examples/offline) that covers both queries and mutations. +We also have an extensive [offline example](./examples/offline) that covers both queries and mutations. [//]: # 'Materials' ## Further reading -For more information about mutations, have a look at [#12: Mastering Mutations in React Query](../community/tkdodos-blog#12-mastering-mutations-in-react-query) from +For more information about mutations, have a look at [#12: Mastering Mutations in React Query](./community/tkdodos-blog#12-mastering-mutations-in-react-query) from the Community Resources. [//]: # 'Materials' diff --git a/docs/framework/react/guides/network-mode.md b/docs/framework/react/guides/network-mode.md index 136163a17e3..ec1d2fc1cf5 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](../guides/queries) and [Mutations](../guides/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](./guides/queries) and [Mutations](./guides/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](../guides/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](./guides/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](../guides/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](./guides/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/placeholder-query-data.md b/docs/framework/react/guides/placeholder-query-data.md index b625d03ed86..c47a95d2089 100644 --- a/docs/framework/react/guides/placeholder-query-data.md +++ b/docs/framework/react/guides/placeholder-query-data.md @@ -14,7 +14,7 @@ There are a few ways to supply placeholder data for a query to the cache before - Declaratively: - Provide `placeholderData` to a query to prepopulate its cache if empty - Imperatively: - - [Prefetch or fetch the data using `queryClient` and the `placeholderData` option](../guides/prefetching) + - [Prefetch or fetch the data using `queryClient` and the `placeholderData` option](./guides/prefetching) When we use `placeholderData`, our Query will not be in a `pending` state - it will start out as being in `success` state, because we have `data` to display - even if that data is just "placeholder" data. To distinguish it from "real" data, we will also have the `isPlaceholderData` flag set to `true` on the Query result. @@ -54,7 +54,7 @@ function Todos() { ## Placeholder Data as a Function -`placeholderData` can also be a function, where you can get access to the data and Query meta information of a "previous" successful Query. This is useful for situations where you want to use the data from one query as the placeholder data for another query. When the QueryKey changes, e.g. from `['todos', 1]` to `['todos', 2]`, we can keep displaying "old" data instead of having to show a loading spinner while data is _transitioning_ from one Query to the next. For more information, see [Paginated Queries](../guides/paginated-queries). +`placeholderData` can also be a function, where you can get access to the data and Query meta information of a "previous" successful Query. This is useful for situations where you want to use the data from one query as the placeholder data for another query. When the QueryKey changes, e.g. from `['todos', 1]` to `['todos', 2]`, we can keep displaying "old" data instead of having to show a loading spinner while data is _transitioning_ from one Query to the next. For more information, see [Paginated Queries](./guides/paginated-queries). [//]: # 'ExampleFunction' @@ -96,6 +96,6 @@ function Todo({ blogPostId }) { ## Further reading -For a comparison between `Placeholder Data` and `Initial Data`, have a look at the [Community Resources](../community/tkdodos-blog#9-placeholder-and-initial-data-in-react-query). +For a comparison between `Placeholder Data` and `Initial Data`, have a look at the [Community Resources](./community/tkdodos-blog#9-placeholder-and-initial-data-in-react-query). [//]: # 'Materials' diff --git a/docs/framework/react/guides/prefetching.md b/docs/framework/react/guides/prefetching.md index 5c3c8386a86..f24b46d8d69 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](../guides/ssr) and the [Advanced Server Rendering guide](../guides/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](./guides/ssr) and the [Advanced Server Rendering guide](./guides/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](../guides/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](./guides/request-waterfalls). ## prefetchQuery & prefetchInfiniteQuery @@ -275,7 +275,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](../guides/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](./guides/request-waterfalls): [//]: # 'ExampleConditionally1' @@ -375,7 +375,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](../guides/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](./guides/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/examples/react/with-react-query?file=src%2Fmain.tsx) over in the [Tanstack Router docs](https://tanstack.com/router/v1/docs). @@ -420,13 +420,13 @@ const articleRoute = new Route({ }) ``` -Integration with other routers is also possible, see the [React Router example](../examples/react-router) for another demonstration. +Integration with other routers is also possible, see the [React Router example](./examples/react-router) for another demonstration. [//]: # 'Router' ## 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' @@ -439,8 +439,8 @@ queryClient.setQueryData(['todos'], todos) ## Further reading -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. +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](../guides/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](./guides/ssr). [//]: # 'Materials' diff --git a/docs/framework/react/guides/queries.md b/docs/framework/react/guides/queries.md index 9965208c58b..85e2370c615 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](../guides/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](./guides/mutations) instead. To subscribe to a query in your components or custom hooks, call the `useQuery` hook with at least: @@ -121,7 +121,7 @@ TypeScript will also narrow the type of `data` correctly if you've checked for ` In addition to the `status` field, you will also get an additional `fetchStatus` property with the following options: - `fetchStatus === 'fetching'` - The query is currently fetching. -- `fetchStatus === 'paused'` - The query wanted to fetch, but it is paused. Read more about this in the [Network Mode](../guides/network-mode) guide. +- `fetchStatus === 'paused'` - The query wanted to fetch, but it is paused. Read more about this in the [Network Mode](./guides/network-mode) guide. - `fetchStatus === 'idle'` - The query is not doing anything at the moment. ### Why two different states? @@ -140,6 +140,6 @@ So keep in mind that a query can be in `pending` state without actually fetching ## Further Reading -For an alternative way of performing status checks, have a look at the [Community Resources](../community/tkdodos-blog#4-status-checks-in-react-query). +For an alternative way of performing status checks, have a look at the [Community Resources](./community/tkdodos-blog#4-status-checks-in-react-query). [//]: # 'Materials' diff --git a/docs/framework/react/guides/query-functions.md b/docs/framework/react/guides/query-functions.md index a9fce20f68b..d6a5949fa74 100644 --- a/docs/framework/react/guides/query-functions.md +++ b/docs/framework/react/guides/query-functions.md @@ -99,14 +99,14 @@ function fetchTodoList({ queryKey }) { The `QueryFunctionContext` is the object passed to each query function. It consists of: -- `queryKey: QueryKey`: [Query Keys](../guides/query-keys) +- `queryKey: QueryKey`: [Query Keys](./guides/query-keys) - `signal?: AbortSignal` - [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) instance provided by TanStack Query - - Can be used for [Query Cancellation](../guides/query-cancellation) + - Can be used for [Query Cancellation](./guides/query-cancellation) - `meta: Record | undefined` - an optional field you can fill with additional information about your query -Additionally, [Infinite Queries](../guides/infinite-queries) get the following options passed: +Additionally, [Infinite Queries](./guides/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 6fb7b790224..93e026181d4 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](../guides/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](./guides/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/query-keys.md b/docs/framework/react/guides/query-keys.md index e6966ede731..af289d17ce2 100644 --- a/docs/framework/react/guides/query-keys.md +++ b/docs/framework/react/guides/query-keys.md @@ -91,13 +91,13 @@ function Todos({ todoId }) { [//]: # 'Example5' -Note that query keys act as dependencies for your query functions. Adding dependent variables to your query key will ensure that queries are cached independently, and that any time a variable changes, _queries will be refetched automatically_ (depending on your `staleTime` settings). See the [exhaustive-deps](../eslint/exhaustive-deps) section for more information and examples. +Note that query keys act as dependencies for your query functions. Adding dependent variables to your query key will ensure that queries are cached independently, and that any time a variable changes, _queries will be refetched automatically_ (depending on your `staleTime` settings). See the [exhaustive-deps](./eslint/exhaustive-deps) section for more information and examples. [//]: # 'Materials' ## Further reading -For tips on organizing Query Keys in larger applications, have a look at [Effective React Query Keys](../community/tkdodos-blog#8-effective-react-query-keys) and check the [Query Key Factory Package](../community/community-projects#query-key-factory) from +For tips on organizing Query Keys in larger applications, have a look at [Effective React Query Keys](./community/tkdodos-blog#8-effective-react-query-keys) and check the [Query Key Factory Package](./community/community-projects#query-key-factory) from the Community Resources. [//]: # 'Materials' diff --git a/docs/framework/react/guides/query-options.md b/docs/framework/react/guides/query-options.md index 8b9c4c1c3ed..6894b0e119c 100644 --- a/docs/framework/react/guides/query-options.md +++ b/docs/framework/react/guides/query-options.md @@ -3,7 +3,7 @@ id: query-options title: Query Options --- -One of the best ways to share `queryKey` and `queryFn` between multiple places, yet keep them co-located to one another, is to use the `queryOptions` helper. At runtime, this helper just returns whatever you pass into it, but it has a lot of advantages when using it [with TypeScript](../typescript#typing-query-options). You can define all possible options for a query in one place, and you'll also get type inference and type safety for all of them. +One of the best ways to share `queryKey` and `queryFn` between multiple places, yet keep them co-located to one another, is to use the `queryOptions` helper. At runtime, this helper just returns whatever you pass into it, but it has a lot of advantages when using it [with TypeScript](./typescript#typing-query-options). You can define all possible options for a query in one place, and you'll also get type inference and type safety for all of them. [//]: # 'Example1' diff --git a/docs/framework/react/guides/request-waterfalls.md b/docs/framework/react/guides/request-waterfalls.md index 811df1a19bd..e9b0fddf0cc 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](../guides/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](./guides/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](../guides/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](./guides/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](../guides/advanced-ssr) further teaches you how to apply these patterns to Server Components and Streaming Server Rendering. +The [Advanced Server Rendering guide](./guides/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](../guides/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](./guides/dependent-queries), that is, it depends on data from the first query when fetching: ```tsx // Get the user @@ -91,7 +91,7 @@ const { While not always feasible, for optimal performance it's better to restructure your API so you can fetch both of these in a single query. In the example above, instead of first fetching `getUserByEmail` to be able to `getProjectsByUser`, introducing a new `getProjectsByUserEmail` query would flatten the waterfall. -> Another way to mitigate dependent queries without restructuring your API is to move the waterfall to the server where latency is lower. This is the idea behind Server Components which are covered in the [Advanced Server Rendering guide](../guides/advanced-ssr). +> Another way to mitigate dependent queries without restructuring your API is to move the waterfall to the server where latency is lower. This is the idea behind Server Components which are covered in the [Advanced Server Rendering guide](./guides/advanced-ssr). Another example of serial queries is when you use React Query with Suspense: @@ -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](../guides/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](./guides/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](../guides/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](./guides/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](../guides/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](./guides/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,14 +317,14 @@ 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](../guides/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](./guides/prefetching). > The tradeoff between: > > - Include all data fetching code in the main bundle, even if we seldom use it > - Put the data fetching code in the code split bundle, but with a request waterfall > -> is not great and has been one of the motivations for Server Components. With Server Components, it's possible to avoid both, read more about how this applies to React Query in the [Advanced Server Rendering guide](../guides/advanced-ssr). +> is not great and has been one of the motivations for Server Components. With Server Components, it's possible to avoid both, read more about how this applies to React Query in the [Advanced Server Rendering guide](./guides/advanced-ssr). ## Summary and takeaways @@ -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](../guides/prefetching). +In the next guide, we'll look at more ways to flatten waterfalls, by leveraging [Prefetching & Router Integration](./guides/prefetching). diff --git a/docs/framework/react/guides/ssr.md b/docs/framework/react/guides/ssr.md index 42e84251fd4..e79bbe789d2 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](../guides/prefetching) for some background. You might also want to check out the [Performance & Request Waterfalls guide](../guides/request-waterfalls) before that. +See the guide on [Prefetching & Router Integration](./guides/prefetching) for some background. You might also want to check out the [Performance & Request Waterfalls guide](./guides/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](../guides/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](./guides/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. @@ -177,11 +177,11 @@ With just a little more setup, you can use a `queryClient` to prefetch queries d > An interesting detail is that there are actually _three_ `queryClient`s involved. The framework loaders are a form of "preloading" phase that happens before rendering, and this phase has it's own `queryClient` that does the prefetching. The dehydrated result of this phase gets passed to **both** the server rendering process **and** the client rendering process which each has it's own `queryClient`. This ensures they both start with the same data so they can return the same markup. -> Server Components are another form of "preloading" phase, that can also "preload" (pre-render) parts of a React component tree. Read more in the [Advanced Server Rendering guide](../guides/advanced-ssr). +> Server Components are another form of "preloading" phase, that can also "preload" (pre-render) parts of a React component tree. Read more in the [Advanced Server Rendering guide](./guides/advanced-ssr). ### Full Next.js pages router example -> For app router documentation, see the [Advanced Server Rendering guide](../guides/advanced-ssr). +> For app router documentation, see the [Advanced Server Rendering guide](./guides/advanced-ssr). Initial setup: @@ -381,7 +381,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](../guides/prefetching#dependent-queries--code-splitting), but how do we do this in framework loaders? Consider the following code, taken from the [Dependent Queries guide](../guides/dependent-queries): +Over in the Prefetching guide we learned how to [prefetch dependent queries](./guides/prefetching#dependent-queries--code-splitting), but how do we do this in framework loaders? Consider the following code, taken from the [Dependent Queries guide](./guides/dependent-queries): ```tsx // Get the user @@ -477,7 +477,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](../guides/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](../guides/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](./guides/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](./guides/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) @@ -523,7 +523,7 @@ Modern frameworks often tries to solve this by fetching the initial code and dat 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](../guides/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](./guides/advanced-ssr). ## Tips, Tricks and Caveats @@ -541,9 +541,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 7820aa22cfc..0c1809deb76 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) 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. @@ -106,7 +106,7 @@ const App: React.FC = () => { ## 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](../guides/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](./guides/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 @@ -135,4 +135,4 @@ 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](../guides/advanced-ssr) guide. +For more information, check out the [NextJs Suspense Streaming Example](./examples/nextjs-suspense-streaming) and the [Advanced Rendering & Hydration](./guides/advanced-ssr) guide. diff --git a/docs/framework/react/guides/testing.md b/docs/framework/react/guides/testing.md index 7a9bf3d00dc..7c73e47eb95 100644 --- a/docs/framework/react/guides/testing.md +++ b/docs/framework/react/guides/testing.md @@ -179,5 +179,5 @@ _Note_: when using React 18, the semantics of `waitFor` have changed as noted ab ## Further reading -For additional tips and an alternative setup using `mock-service-worker`, have a look at [Testing React Query](../community/tkdodos-blog#5-testing-react-query) from +For additional tips and an alternative setup using `mock-service-worker`, have a look at [Testing React Query](./community/tkdodos-blog#5-testing-react-query) from the Community Resources. diff --git a/docs/framework/react/guides/updates-from-mutation-responses.md b/docs/framework/react/guides/updates-from-mutation-responses.md index c2d5a6e65ab..18295802348 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' diff --git a/docs/framework/react/plugins/createAsyncStoragePersister.md b/docs/framework/react/plugins/createAsyncStoragePersister.md index 2bda27e9a0f..28ba7dd098e 100644 --- a/docs/framework/react/plugins/createAsyncStoragePersister.md +++ b/docs/framework/react/plugins/createAsyncStoragePersister.md @@ -28,7 +28,7 @@ yarn add @tanstack/query-async-storage-persister @tanstack/react-query-persist-c - Import the `createAsyncStoragePersister` function - Create a new asyncStoragePersister - you can pass any `storage` to it that adheres to the `AsyncStorage` interface - the example below uses the async-storage from React Native -- Wrap your app by using [`PersistQueryClientProvider`](../plugins/persistQueryClient.md#persistqueryclientprovider) component. +- Wrap your app by using [`PersistQueryClientProvider`](./plugins/persistQueryClient.md#persistqueryclientprovider) component. ```tsx import AsyncStorage from '@react-native-async-storage/async-storage' @@ -62,7 +62,7 @@ export default Root ## Retries -Retries work the same as for a [SyncStoragePersister](../plugins/createSyncStoragePersister), except that they can also be asynchronous. You can also use all the predefined retry handlers. +Retries work the same as for a [SyncStoragePersister](./plugins/createSyncStoragePersister), except that they can also be asynchronous. You can also use all the predefined retry handlers. ## API diff --git a/docs/framework/react/plugins/createSyncStoragePersister.md b/docs/framework/react/plugins/createSyncStoragePersister.md index 9f0e97c74cf..4b7ba3b97da 100644 --- a/docs/framework/react/plugins/createSyncStoragePersister.md +++ b/docs/framework/react/plugins/createSyncStoragePersister.md @@ -27,7 +27,7 @@ yarn add @tanstack/query-sync-storage-persister @tanstack/react-query-persist-cl - Import the `createSyncStoragePersister` function - Create a new syncStoragePersister -- Pass it to the [`persistQueryClient`](../plugins/persistQueryClient) function +- Pass it to the [`persistQueryClient`](./plugins/persistQueryClient) function ```tsx import { persistQueryClient } from '@tanstack/react-query-persist-client' diff --git a/docs/framework/react/plugins/persistQueryClient.md b/docs/framework/react/plugins/persistQueryClient.md index 246a1c4388f..24e208a31fe 100644 --- a/docs/framework/react/plugins/persistQueryClient.md +++ b/docs/framework/react/plugins/persistQueryClient.md @@ -7,8 +7,8 @@ This is set of utilities for interacting with "persisters" which save your query ## Build Persisters -- [createSyncStoragePersister](../plugins/createSyncStoragePersister) -- [createAsyncStoragePersister](../plugins/createAsyncStoragePersister) +- [createSyncStoragePersister](./plugins/createSyncStoragePersister) +- [createAsyncStoragePersister](./plugins/createAsyncStoragePersister) - [create a custom persister](#persisters) ## How It Works @@ -56,7 +56,7 @@ the persister `removeClient()` is called and the cache is immediately discarded. ### `persistQueryClientSave` -- Your query/mutation are [`dehydrated`](../reference/hydration#dehydrate) and stored by the persister you provided. +- Your query/mutation are [`dehydrated`](./reference/hydration#dehydrate) and stored by the persister you provided. - `createSyncStoragePersister` and `createAsyncStoragePersister` throttle this action to happen at most every 1 second to save on potentially expensive writes. Review their documentation to see how to customize their throttle timing. You can use this to explicitly persist the cache at the moment(s) you choose. @@ -88,7 +88,7 @@ persistQueryClientSubscribe({ ### `persistQueryClientRestore` -- Attempts to [`hydrate`](../reference/hydration#hydrate) a previously persisted dehydrated query/mutation cache from the persister back into the query cache of the passed query client. +- Attempts to [`hydrate`](./reference/hydration#hydrate) a previously persisted dehydrated query/mutation cache from the persister back into the query cache of the passed query client. - If a cache is found that is older than the `maxAge` (which by default is 24 hours), it will be discarded. This timing can be customized as you see fit. You can use this to restore the cache at moment(s) you choose. @@ -178,7 +178,7 @@ ReactDOM.createRoot(rootElement).render() ### PersistQueryClientProvider -For this use-case, you can use the `PersistQueryClientProvider`. It will make sure to subscribe / unsubscribe correctly according to the React component lifecycle, and it will also make sure that queries will not start fetching while we are still restoring. Queries will still render though, they will just be put into `fetchingState: 'idle'` until data has been restored. Then, they will refetch unless the restored data is _fresh_ enough, and _initialData_ will also be respected. It can be used _instead of_ the normal [QueryClientProvider](../reference/QueryClientProvider): +For this use-case, you can use the `PersistQueryClientProvider`. It will make sure to subscribe / unsubscribe correctly according to the React component lifecycle, and it will also make sure that queries will not start fetching while we are still restoring. Queries will still render though, they will just be put into `fetchingState: 'idle'` until data has been restored. Then, they will refetch unless the restored data is _fresh_ enough, and _initialData_ will also be respected. It can be used _instead of_ the normal [QueryClientProvider](./reference/QueryClientProvider): ```tsx import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client' @@ -208,14 +208,14 @@ ReactDOM.createRoot(rootElement).render( #### Props -`PersistQueryClientProvider` takes the same props as [QueryClientProvider](../reference/QueryClientProvider), and additionally: +`PersistQueryClientProvider` takes the same props as [QueryClientProvider](./reference/QueryClientProvider), and additionally: - `persistOptions: PersistQueryClientOptions` - all [options](#options) you can pass to [persistQueryClient](#persistqueryclient) minus the QueryClient itself - `onSuccess?: () => Promise | unknown` - optional - will be called when the initial restore is finished - - can be used to [resumePausedMutations](../reference/QueryClient#queryclientresumepausedmutations) + - can be used to [resumePausedMutations](./reference/QueryClient#queryclientresumepausedmutations) - if a Promise is returned, it will be awaited; restoring is seen as ongoing until then ### useIsRestoring diff --git a/docs/framework/react/reference/infiniteQueryOptions.md b/docs/framework/react/reference/infiniteQueryOptions.md index 72c0497d412..d29b833f591 100644 --- a/docs/framework/react/reference/infiniteQueryOptions.md +++ b/docs/framework/react/reference/infiniteQueryOptions.md @@ -12,7 +12,7 @@ infiniteQueryOptions({ **Options** -You can generally pass everything to `queryOptions` that you can also pass to [`useInfiniteQuery`](../reference/useInfiniteQuery). Some options will have no effect when then forwarded to a function like `queryClient.prefetchInfiniteQuery`, but TypeScript will still be fine with those excess properties. +You can generally pass everything to `queryOptions` that you can also pass to [`useInfiniteQuery`](./reference/useInfiniteQuery). Some options will have no effect when then forwarded to a function like `queryClient.prefetchInfiniteQuery`, but TypeScript will still be fine with those excess properties. - `queryKey: QueryKey` - **Required** diff --git a/docs/framework/react/reference/queryOptions.md b/docs/framework/react/reference/queryOptions.md index 79f73075417..a758037145e 100644 --- a/docs/framework/react/reference/queryOptions.md +++ b/docs/framework/react/reference/queryOptions.md @@ -12,7 +12,7 @@ queryOptions({ **Options** -You can generally pass everything to `queryOptions` that you can also pass to [`useQuery`](../reference/useQuery). Some options will have no effect when then forwarded to a function like `queryClient.prefetchQuery`, but TypeScript will still be fine with those excess properties. +You can generally pass everything to `queryOptions` that you can also pass to [`useQuery`](./reference/useQuery). Some options will have no effect when then forwarded to a function like `queryClient.prefetchQuery`, but TypeScript will still be fine with those excess properties. - `queryKey: QueryKey` - **Required** diff --git a/docs/framework/react/reference/useInfiniteQuery.md b/docs/framework/react/reference/useInfiniteQuery.md index 87190c0bbe3..c9f02ab91ce 100644 --- a/docs/framework/react/reference/useInfiniteQuery.md +++ b/docs/framework/react/reference/useInfiniteQuery.md @@ -26,12 +26,12 @@ const { **Options** -The options for `useInfiniteQuery` are identical to the [`useQuery` hook](../reference/useQuery) with the addition of the following: +The options for `useInfiniteQuery` are identical to the [`useQuery` hook](./reference/useQuery) with the addition of the following: - `queryFn: (context: QueryFunctionContext) => Promise` - - **Required, but only if no default query function has been defined** [`defaultQueryFn`](../guides/default-query-function) + - **Required, but only if no default query function has been defined** [`defaultQueryFn`](./guides/default-query-function) - The function that the query will use to request data. - - Receives a [QueryFunctionContext](../guides/query-functions#queryfunctioncontext) + - Receives a [QueryFunctionContext](./guides/query-functions#queryfunctioncontext) - Must return a promise that will either resolve data or throw an error. - `initialPageParam: TPageParam` - **Required** @@ -54,7 +54,7 @@ The options for `useInfiniteQuery` are identical to the [`useQuery` hook](../ref **Returns** -The returned properties for `useInfiniteQuery` are identical to the [`useQuery` hook](../reference/useQuery), with the addition of the following and a small difference in `isRefetching`: +The returned properties for `useInfiniteQuery` are identical to the [`useQuery` hook](./reference/useQuery), with the addition of the following and a small difference in `isRefetching`: - `data.pages: TData[]` - Array containing all pages. diff --git a/docs/framework/react/reference/useIsFetching.md b/docs/framework/react/reference/useIsFetching.md index d35a06a67e1..64a735a1906 100644 --- a/docs/framework/react/reference/useIsFetching.md +++ b/docs/framework/react/reference/useIsFetching.md @@ -15,7 +15,7 @@ const isFetchingPosts = useIsFetching({ queryKey: ['posts'] }) **Options** -- `filters?: QueryFilters`: [Query Filters](../guides/filters#query-filters) +- `filters?: QueryFilters`: [Query Filters](./guides/filters#query-filters) - `queryClient?: QueryClient`, - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used. diff --git a/docs/framework/react/reference/useIsMutating.md b/docs/framework/react/reference/useIsMutating.md index 7ad18498912..93b2634b951 100644 --- a/docs/framework/react/reference/useIsMutating.md +++ b/docs/framework/react/reference/useIsMutating.md @@ -15,7 +15,7 @@ const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] }) **Options** -- `filters?: MutationFilters`: [Mutation Filters](../guides/filters#mutation-filters) +- `filters?: MutationFilters`: [Mutation Filters](./guides/filters#mutation-filters) - `queryClient?: QueryClient`, - Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used. diff --git a/docs/framework/react/reference/useMutation.md b/docs/framework/react/reference/useMutation.md index 1c7c63af2ab..42e55a33c8f 100644 --- a/docs/framework/react/reference/useMutation.md +++ b/docs/framework/react/reference/useMutation.md @@ -57,7 +57,7 @@ mutate(variables, { - `networkMode: 'online' | 'always' | 'offlineFirst` - optional - defaults to `'online'` - - see [Network Mode](../guides/network-mode) for more information. + - see [Network Mode](./guides/network-mode) for more information. - `onMutate: (variables: TVariables) => Promise | TContext | void` - Optional - This function will fire before the mutation function is fired and is passed the same variables the mutation function would receive @@ -126,7 +126,7 @@ mutate(variables, { - `isIdle`, `isPending`, `isSuccess`, `isError`: boolean variables derived from `status` - `isPaused: boolean` - will be `true` if the mutation has been `paused` - - see [Network Mode](../guides/network-mode) for more information. + - see [Network Mode](./guides/network-mode) for more information. - `data: undefined | unknown` - Defaults to `undefined` - The last successfully resolved data for the query. diff --git a/docs/framework/react/reference/useMutationState.md b/docs/framework/react/reference/useMutationState.md index ef112b07635..4d988614c34 100644 --- a/docs/framework/react/reference/useMutationState.md +++ b/docs/framework/react/reference/useMutationState.md @@ -41,7 +41,7 @@ const data = useMutationState({ **Options** - `options` - - `filters?: MutationFilters`: [Mutation Filters](../guides/filters#mutation-filters) + - `filters?: MutationFilters`: [Mutation Filters](./guides/filters#mutation-filters) - `select?: (mutation: Mutation) => TResult` - Use this to transform the mutation state. - `queryClient?: QueryClient`, diff --git a/docs/framework/react/reference/useQueries.md b/docs/framework/react/reference/useQueries.md index 25bfdf068bc..b0844762bad 100644 --- a/docs/framework/react/reference/useQueries.md +++ b/docs/framework/react/reference/useQueries.md @@ -16,7 +16,7 @@ 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) (excluding the `queryClient` option - because the `QueryClient` can be passed in on the top level). +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 `queryClient` option - because the `QueryClient` can be passed in on the top level). - `queryClient?: QueryClient` - Use this to provide a custom QueryClient. Otherwise, the one from the nearest context will be used. diff --git a/docs/framework/react/reference/useQuery.md b/docs/framework/react/reference/useQuery.md index 801017d0f1b..f600dc5579f 100644 --- a/docs/framework/react/reference/useQuery.md +++ b/docs/framework/react/reference/useQuery.md @@ -63,20 +63,20 @@ const { - `queryKey: unknown[]` - **Required** - The query key to use for this query. - - The query key will be hashed into a stable hash. See [Query Keys](../guides/query-keys) for more information. + - The query key will be hashed into a stable hash. See [Query Keys](./guides/query-keys) for more information. - The query will automatically update when this key changes (as long as `enabled` is not set to `false`). - `queryFn: (context: QueryFunctionContext) => Promise` - - **Required, but only if no default query function has been defined** See [Default Query Function](../guides/default-query-function) for more information. + - **Required, but only if no default query function has been defined** See [Default Query Function](./guides/default-query-function) for more information. - The function that the query will use to request data. - - Receives a [QueryFunctionContext](../guides/query-functions#queryfunctioncontext) + - Receives a [QueryFunctionContext](./guides/query-functions#queryfunctioncontext) - Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. - `enabled: boolean` - Set this to `false` to disable this query from automatically running. - - Can be used for [Dependent Queries](../guides/dependent-queries). + - Can be used for [Dependent Queries](./guides/dependent-queries). - `networkMode: 'online' | 'always' | 'offlineFirst` - optional - defaults to `'online'` - - see [Network Mode](../guides/network-mode) for more information. + - see [Network Mode](./guides/network-mode) for more information. - `retry: boolean | number | (failureCount: number, error: TError) => boolean` - If `false`, failed queries will not retry by default. - If `true`, failed queries will retry infinitely. @@ -208,7 +208,7 @@ const { - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetches. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - - see [Network Mode](../guides/network-mode) for more information. + - see [Network Mode](./guides/network-mode) for more information. - `isFetching: boolean` - A derived boolean from the `fetchStatus` variable above, provided for convenience. - `isPaused: boolean` diff --git a/docs/framework/react/reference/useSuspenseInfiniteQuery.md b/docs/framework/react/reference/useSuspenseInfiniteQuery.md index a1d1fa43b00..5eb2eb7cceb 100644 --- a/docs/framework/react/reference/useSuspenseInfiniteQuery.md +++ b/docs/framework/react/reference/useSuspenseInfiniteQuery.md @@ -9,7 +9,7 @@ const result = useSuspenseInfiniteQuery(options) **Options** -The same as for [useInfiniteQuery](../reference/useInfiniteQuery), except for: +The same as for [useInfiniteQuery](./reference/useInfiniteQuery), except for: - `suspense` - `throwOnError` @@ -18,7 +18,7 @@ The same as for [useInfiniteQuery](../reference/useInfiniteQuery), except for: **Returns** -Same object as [useInfiniteQuery](../reference/useInfiniteQuery), except that: +Same object as [useInfiniteQuery](./reference/useInfiniteQuery), except that: - `data` is guaranteed to be defined - `isPlaceholderData` is missing diff --git a/docs/framework/react/reference/useSuspenseQueries.md b/docs/framework/react/reference/useSuspenseQueries.md index 9d1a4be46d2..ac164c150f2 100644 --- a/docs/framework/react/reference/useSuspenseQueries.md +++ b/docs/framework/react/reference/useSuspenseQueries.md @@ -9,7 +9,7 @@ const result = useSuspenseQueries(options) **Options** -The same as for [useQueries](../reference/useQueries), except that each `query` can't have: +The same as for [useQueries](./reference/useQueries), except that each `query` can't have: - `suspense` - `throwOnError` @@ -18,7 +18,7 @@ The same as for [useQueries](../reference/useQueries), except that each `query` **Returns** -Same structure as [useQueries](../reference/useQueries), except that for each `query`: +Same structure as [useQueries](./reference/useQueries), except that for each `query`: - `data` is guaranteed to be defined - `isPlaceholderData` is missing diff --git a/docs/framework/react/reference/useSuspenseQuery.md b/docs/framework/react/reference/useSuspenseQuery.md index 594a4c13aa2..4adf43f39a5 100644 --- a/docs/framework/react/reference/useSuspenseQuery.md +++ b/docs/framework/react/reference/useSuspenseQuery.md @@ -9,7 +9,7 @@ const result = useSuspenseQuery(options) **Options** -The same as for [useQuery](../reference/useQuery), except for: +The same as for [useQuery](./reference/useQuery), except for: - `suspense` - `throwOnError` @@ -18,7 +18,7 @@ The same as for [useQuery](../reference/useQuery), except for: **Returns** -Same object as [useQuery](../reference/useQuery), except that: +Same object as [useQuery](./reference/useQuery), except that: - `data` is guaranteed to be defined - `isPlaceholderData` is missing diff --git a/docs/framework/svelte/installation.md b/docs/framework/svelte/installation.md index 11d58e69643..2e4bc94e969 100644 --- a/docs/framework/svelte/installation.md +++ b/docs/framework/svelte/installation.md @@ -17,4 +17,4 @@ $ pnpm add @tanstack/svelte-query $ yarn add @tanstack/svelte-query ``` -> Wanna give it a spin before you download? Try out the [basic](/query/v4/docs/svelte/examples/svelte/basic) example! +> Wanna give it a spin before you download? Try out the [basic](./examples/basic) example! diff --git a/docs/framework/svelte/ssr.md b/docs/framework/svelte/ssr.md index 9302c009cf2..2c51b170cce 100644 --- a/docs/framework/svelte/ssr.md +++ b/docs/framework/svelte/ssr.md @@ -34,7 +34,7 @@ The recommended way to achieve this is to use the `browser` module from SvelteKi Svelte Query supports two ways of prefetching data on the server and passing that to the client with SvelteKit. -If you wish to view the ideal SSR setup, please have a look at the [SSR example](../examples/svelte/ssr). +If you wish to view the ideal SSR setup, please have a look at the [SSR example](./examples/ssr). ### Using `initialData` diff --git a/docs/framework/vue/guides/ssr.md b/docs/framework/vue/guides/ssr.md index 9f3137bda05..ae0d92079e2 100644 --- a/docs/framework/vue/guides/ssr.md +++ b/docs/framework/vue/guides/ssr.md @@ -235,6 +235,6 @@ In case you are creating the `QueryClient` for every request, Vue Query creates 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. -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/vue/guides/suspense.md b/docs/framework/vue/guides/suspense.md index e83ad15e889..e6251545ef9 100644 --- a/docs/framework/vue/guides/suspense.md +++ b/docs/framework/vue/guides/suspense.md @@ -51,4 +51,4 @@ export default defineComponent({ ## Fetch-on-render vs Render-as-you-fetch -Out of the box, Vue 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](../guides/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, Vue 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](./guides/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. diff --git a/docs/framework/vue/installation.md b/docs/framework/vue/installation.md index ccaa572b453..fe046c653f7 100644 --- a/docs/framework/vue/installation.md +++ b/docs/framework/vue/installation.md @@ -17,7 +17,7 @@ $ pnpm add @tanstack/vue-query $ yarn add @tanstack/vue-query ``` -> Wanna give it a spin before you download? Try out the [basic](../examples/vue/basic) example! +> Wanna give it a spin before you download? Try out the [basic](./examples/basic) example! Vue Query is compatible with Vue 2.x and 3.x diff --git a/docs/framework/vue/overview.md b/docs/framework/vue/overview.md index 31c8da66ffc..91e3ed902c9 100644 --- a/docs/framework/vue/overview.md +++ b/docs/framework/vue/overview.md @@ -11,6 +11,6 @@ replace: { 'React': 'Vue', 'react-query': 'vue-query' } ## You talked me into it, so what now? -- Learn Vue Query at your own pace with our amazingly thorough [Walkthrough Guide](../installation) and [API Reference](../reference/useQuery) +- Learn Vue Query at your own pace with our amazingly thorough [Walkthrough Guide](./installation) and [API Reference](./reference/useQuery) [//]: # 'Materials' diff --git a/docs/framework/vue/quick-start.md b/docs/framework/vue/quick-start.md index eb35cfc3fe9..fac18038ac7 100644 --- a/docs/framework/vue/quick-start.md +++ b/docs/framework/vue/quick-start.md @@ -7,7 +7,7 @@ replace: { 'React': 'Vue', 'react-query': 'vue-query' } [//]: # 'Example' -If you're looking for a fully functioning example, please have a look at our [basic codesandbox example](../examples/vue/basic) +If you're looking for a fully functioning example, please have a look at our [basic codesandbox example](./examples/basic) ```vue