Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(docs): broken internal links in the query docs #7247

Merged
merged 10 commits into from Apr 22, 2024
2 changes: 1 addition & 1 deletion docs/framework/angular/guides/caching.md
Expand Up @@ -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`](../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**).
Expand Down
2 changes: 1 addition & 1 deletion docs/framework/angular/overview.md
Expand Up @@ -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](../injectQuery)
- Learn Angular Query at your own pace with our amazingly thorough [Walkthrough Guide](../installation) and [API Reference](../reference/injectQuery)
2 changes: 1 addition & 1 deletion docs/framework/react/guides/advanced-ssr.md
Expand Up @@ -421,7 +421,7 @@ 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.

Expand Down
2 changes: 1 addition & 1 deletion docs/framework/react/guides/caching.md
Expand Up @@ -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`](../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**).
Expand Down
2 changes: 1 addition & 1 deletion docs/framework/react/guides/dependent-queries.md
Expand Up @@ -90,6 +90,6 @@ const usersMessages = useQueries({

## A note about performance

Dependent queries by definition constitutes a form of [request waterfall](../request-waterfalls), which hurts performance. If we pretend both queries take the same amount of time, doing them serially instead of in parallel always takes twice as much time, which is especially hurtful when it happens on a client that has high latency. If you can, it's always better to restructure the backend APIs so that both queries can be fetched in parallel, though that might not always be practically feasible.
Dependent queries by definition constitutes a form of [request waterfall](../../../react/guides/request-waterfalls), which hurts performance. If we pretend both queries take the same amount of time, doing them serially instead of in parallel always takes twice as much time, which is especially hurtful when it happens on a client that has high latency. If you can, it's always better to restructure the backend APIs so that both queries can be fetched in parallel, though that might not always be practically feasible.

In the example above, instead of first fetching `getUserByEmail` to be able to `getProjectsByUser`, introducing a new `getProjectsByUserEmail` query would flatten the waterfall.
4 changes: 2 additions & 2 deletions docs/framework/react/guides/important-defaults.md
Expand Up @@ -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](../tkdodos-blog#1-practical-react-query)
- [React Query as a State Manager](../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)
Comment on lines +39 to +40
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looking at the file structure, we are in:

docs/framework/react/guides/important-defaults.md

and we want to link towards

docs/framework/react/community/tkdodos-blog.md

so imo the correct link should be one level up:

../community/tkdodos-blog

this is also what my editor would auto-complete. So why are two levels up (../../ ) needed ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure why the two ..-s are needed. I just assumed that it's related to the conversation in the in the #router-maintainers channel in Discord about trailing slashes, and VSCode improperly flagging links with errors, because it did not work the VSCode-way. 🤣 (Still doesn't, I checked.)

I'll ask around in Discord, and come back with the answer.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's my question on Discord with my most recent theory on why this solution works... 😅

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I presented this theory to Tanner, and he said it's correct:

  1. the file is docs/framework/react/guides/important-defaults.md
  2. we want to link to docs/framework/react/community/tkdodos-blog.md
  3. the relative link that works is ../../community/tkdods.md

My theory on why we need two ..-s here:

  • somewhere along the way the original markdown gets interpreted as the docs/framework/react/guides/important-defaults/ route
  • . parent is important-defaults
  • .. grandparent is guides
  • ../.. great-grandparent is react

Hence ./../../community takes us to the community route in the current path's great-grandparent route.


[//]: # 'Materials'
6 changes: 3 additions & 3 deletions docs/framework/react/guides/initial-query-data.md
Expand Up @@ -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`](../prefetching)
- [Manually place the data into the cache using `queryClient.setQueryData`](../prefetching)
- [Prefetch the data using `queryClient.prefetchQuery`](../../../react/guides/prefetching)
- [Manually place the data into the cache using `queryClient.setQueryData`](../../../react/guides/prefetching)

## Using `initialData` to prepopulate a query

Expand Down Expand Up @@ -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](../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'
4 changes: 2 additions & 2 deletions docs/framework/react/guides/migrating-to-react-query-3.md
Expand Up @@ -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](../QueryErrorResetBoundary)
- [useQueryErrorResetBoundary](../useQueryErrorResetBoundary)
- [QueryErrorResetBoundary](../../reference/QueryErrorResetBoundary)
- [useQueryErrorResetBoundary](../../reference/useQueryErrorResetBoundary)

### `QueryCache.getQuery()` has been replaced by `QueryCache.find()`.

Expand Down
10 changes: 5 additions & 5 deletions docs/framework/react/guides/migrating-to-react-query-4.md
Expand Up @@ -134,7 +134,7 @@ The `useQueries` hook now accepts an object with a `queries` prop as its input.

### Undefined is an illegal cache value for successful queries

In order to make bailing out of updates possible by returning `undefined`, we had to make `undefined` an illegal cache value. This is in-line with other concepts of react-query, for example, returning `undefined` from the [initialData function](guides/initial-query-data#initial-data-function) will also _not_ set data.
In order to make bailing out of updates possible by returning `undefined`, we had to make `undefined` an illegal cache value. This is in-line with other concepts of react-query, for example, returning `undefined` from the [initialData function](../initial-query-data#initial-data-function) will also _not_ set data.

Further, it is an easy bug to produce `Promise<void>` by adding logging in the queryFn:

Expand Down Expand Up @@ -234,7 +234,7 @@ The filter defaults to `all`, and you can choose to only match `active` or `inac

#### refetchActive / refetchInactive

[queryClient.invalidateQueries](../QueryClient#queryclientinvalidatequeries) had two additional, similar flags:
[queryClient.invalidateQueries](../../../../reference/QueryClient/#queryclientinvalidatequeries) had two additional, similar flags:

```
refetchActive: Boolean
Expand Down Expand Up @@ -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`](../createSyncStoragePersister) and [`createAsyncStoragePersister`](../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:

Expand All @@ -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

Expand Down Expand Up @@ -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](../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) =>
Expand Down
10 changes: 5 additions & 5 deletions docs/framework/react/guides/migrating-to-v5.md
Expand Up @@ -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

Expand Down Expand Up @@ -235,7 +235,7 @@ useQuery<number, string>({
})
```

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

Expand Down Expand Up @@ -488,17 +488,17 @@ Infinite Queries can be prefetched like regular Queries. Per default, only the f

### New `combine` option for `useQueries`

See the [useQueries docs](../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](../createPersister) for more details.
See the [experimental_createPersister docs](../../../react/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

Expand Down
8 changes: 4 additions & 4 deletions docs/framework/react/guides/mutations.md
Expand Up @@ -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](../QueryClient#queryclientinvalidatequeries) and the [Query Client's `setQueryData` method](../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'

Expand Down Expand Up @@ -343,7 +343,7 @@ queryClient.resumePausedMutations()

### Persisting Offline mutations

If you persist offline mutations with the [persistQueryClient plugin](../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](../../../react/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`.

Expand Down Expand Up @@ -386,7 +386,7 @@ 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'

Expand All @@ -409,7 +409,7 @@ const mutation = useMutation({

## Further reading

For more information about mutations, have a look at [#12: Mastering Mutations in React Query](../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'
2 changes: 1 addition & 1 deletion docs/framework/react/guides/network-mode.md
Expand Up @@ -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](../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

Expand Down
4 changes: 2 additions & 2 deletions docs/framework/react/guides/placeholder-query-data.md
Expand Up @@ -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](../prefetching)
- [Prefetch or fetch the data using `queryClient` and the `placeholderData` option](../../../react/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.

Expand Down Expand Up @@ -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](../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'
6 changes: 3 additions & 3 deletions docs/framework/react/guides/prefetching.md
Expand Up @@ -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](../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'

Expand All @@ -439,7 +439,7 @@ 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](../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](../ssr).

Expand Down
2 changes: 1 addition & 1 deletion docs/framework/react/guides/queries.md
Expand Up @@ -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](../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'