docs: add tkdodo's blog to the docs (TanStack#2616)

Author: TkDodo

.all-contributorsrc

@@ -134,7 +134,20 @@
       "contributions": [
         "doc"
       ]
-    }
+    },
+    {
+      "login": "tkdodo",
+      "name": "Dominik Dorfmeister",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/1021430?v=4",
+      "profile": "https://tkdodo.eu",
+      "contributions": [
+        "code",
+        "doc",
+        "maintenance",
+        "question",
+        "review"
+      ]
+    },
   ],
   "contributorsPerLine": 7,
   "skipCi": true

README.md

@@ -71,6 +71,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <td align="center"><a href="https://github.com/justincy"><img src="https://avatars2.githubusercontent.com/u/1037458?v=4" width="100px;" alt=""/><br /><sub><b>Justin</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=justincy" title="Code">💻</a></td>
     <td align="center"><a href="http://www.marceloalves.com"><img src="https://avatars1.githubusercontent.com/u/216782?v=4" width="100px;" alt=""/><br /><sub><b>Marcelo Alves</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=MarceloAlves" title="Code">💻</a></td>
     <td align="center"><a href="https://github.com/zorzysty"><img src="https://avatars0.githubusercontent.com/u/5398733?v=4" width="100px;" alt=""/><br /><sub><b>Zorza</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=zorzysty" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://tkdodo.eu"><img src="https://avatars0.githubusercontent.com/u/1021430?v=4" width="100px;" alt=""/><br /><sub><b>Dominik Dorfmeister</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=tkdodo" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/commits?author=tkdodo" title="Documentation">📖</a> <a href="#maintenance-tkdodo" title="Maintenance">🚧</a> <a href="#question-tkdodo" title="Question">💬</a> <a href="https://github.com/tannerlinsley/react-query/pulls?q=is%3Apr+reviewed-by%3Atkdodo" title="Reviewed Pull Requests">👀</a></td>
   </tr>
 </table>
 

docs/src/manifests/manifest.json

@@ -207,6 +207,17 @@
         }
       ]
     },
+    {
+      "title": "Community Resources",
+      "heading": true,
+      "routes": [
+        {
+          "title": "TkDodo's Blog",
+          "path": "/community/tkdodos-blog",
+          "editUrl": "/community/tkdodos-blog.md"
+        }
+      ]
+    },
     {
       "title": "Examples",
       "heading": true,

docs/src/pages/community/tkdodos-blog.md

@@ -0,0 +1,47 @@
+---
+id: tkdodos-blog
+title: TkDodo's Blog
+---
+
+React Query maintainer [TkDodo](https://twitter.com/tkdodo) has a series of blog posts about using and working with the library. Some articles show general best practices, but most have an _opinionated_ point of view.
+
+
+## [#1: Practical React Query](https://tkdodo.eu/blog/practical-react-query)
+
+> An advanced introduction to React Query, showing practical tips that go beyond the docs. It covers explaining the defaults (`staleTime` vs. `cacheTime`), concepts like keeping server and client state separate, handling dependencies and creating custom hooks, as well as outlining why the `enabled` option is very powerful. [Read more...](https://tkdodo.eu/blog/practical-react-query)
+
+## [#2: React Query Data Transformations](https://tkdodo.eu/blog/react-query-data-transformations)
+
+> Learn the possibilities to perform the quite common and important task of transforming your data with React Query. From transforming in the `queryFn` to using the `select` option, this article outlines the pros and cons of all the different approaches. [Read more...](https://tkdodo.eu/blog/react-query-data-transformations)
+
+## [#3: React Query Render Optimizations](https://tkdodo.eu/blog/react-query-render-optimizations)
+
+> Let's take a look at what you can do when your component re-renders too often when using React Query. The library is already pretty optimized, but there are still some opt-in features (like `tracked queries`) that you can use to avoid the `isFetching` transition. We're also looking into what `structural sharing` refers to. [Read more...](https://tkdodo.eu/blog/react-query-render-optimizations)
+
+## [#4: Status Checks in React Query](https://tkdodo.eu/blog/status-checks-in-react-query)
+
+> We usually check for `isLoading` first before checking for `isError` , but sometimes, checking if `data` is available should be the first thing to do. This article shows how the wrong status check order can negatively impact user experience. [Read more...](https://tkdodo.eu/blog/status-checks-in-react-query)
+
+## [#5: Testing React Query](https://tkdodo.eu/blog/testing-react-query)
+
+> The docs already cover pretty well what you need to do to get started when testing React Query. This article shows some additional tips (like turning off `retries` or silencing the `console`) you might want to follow when testing custom hooks or components using them. It also links to an [example repository](https://github.com/TkDodo/testing-react-query) with tests for success and error states, powered by `mock-service-worker`. [Read more...](https://tkdodo.eu/blog/testing-react-query)
+
+## [#6: React Query and TypeScript](https://tkdodo.eu/blog/react-query-and-type-script)
+
+> Since React Query is written in TypeScript, it has great support for it. This blog post explains the various Generics, how you can leverage type inference to avoid having to explicitly type `useQuery` and friends, what to do with `unknown` errors, how type narrowing works and more! [Read more...](https://tkdodo.eu/blog/react-query-and-type-script)
+
+## [#7: Using WebSockets with React Query](https://tkdodo.eu/blog/using-web-sockets-with-react-query)
+
+> A step-by-step guide on how to make real-time notifications work with React Query, with either event-based subscriptions or pushing full data directly to the client. Applicable to anything from the browser native WebSocket API over Firebase and even GraphQL subscriptions. [Read more...](https://tkdodo.eu/blog/using-web-sockets-with-react-query)
+
+## [#8: Effective React Query Keys](https://tkdodo.eu/blog/effective-react-query-keys)
+
+> Most examples just use a simple String or Array Query Key, but how do you organize your keys effectively once your app grows past a todo list? This articles shows you how co-location and Query Key Factories can make your life easier. [Read more...](https://tkdodo.eu/blog/effective-react-query-keys)
+
+## [#9: Placeholder and Initial Data in React Query](https://tkdodo.eu/blog/placeholder-and-initial-data-in-react-query)
+
+> Placeholder and Initial Data are two similar yet different concepts for synchronously showing data instead of a loading spinner to improve the ux of our application. This blog post compares the two and outlines scenarios where each one shines. [Read more...](https://tkdodo.eu/blog/placeholder-and-initial-data-in-react-query)
+
+## [#10: React Query as a State Manager](https://tkdodo.eu/blog/react-query-as-a-state-manager)
+
+> React Query doesn't fetch any data for you - it's a data synchronization tool that excels when used for server state. This article has everything you need to know to make React Query your single source of truth state manager for your async state. You'll learn how to let React Query do it's magic and why customizing `staleTime` might be all you need. [Read more...](https://tkdodo.eu/blog/react-query-as-a-state-manager)

docs/src/pages/guides/important-defaults.md

@@ -31,3 +31,11 @@ If you see a refetch that you are not expecting, it is likely because you just f
 - Query results by default are **structurally shared to detect if data has actually changed** and if not, **the data reference remains unchanged** to better help with value stabilization with regards to useMemo and useCallback. If this concept sounds foreign, then don't worry about it! 99.9% of the time you will not need to disable this and it makes your app more performant at zero cost to you.
 
 > Structural sharing only works with JSON-compatible values, any other value types will always be considered as changed. If you are seeing performance issues because of large responses for example, you can disable this feature with the `config.structuralSharing` flag. If you are dealing with non-JSON compatible values in your query responses and still want to detect if data has changed or not, you can define a data compare function with `config.isDataEqual`.
+
+## Further Reading
+
+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)
+

docs/src/pages/guides/initial-query-data.md

@@ -134,3 +134,7 @@ function Todo({ todoId }) {
   })
 }
 ```
+
+## Further reading
+
+For a comparison between `Initial Data` and `Placholder Data`, have a look at the [Community Resources](../community/tkdodos-blog#9-placeholder-and-initial-data-in-react-query).

docs/src/pages/guides/placeholder-query-data.md

@@ -53,3 +53,7 @@ function Todo({ blogPostId }) {
   })
 }
 ```
+
+## Further reading
+
+For a comparison between `Placholder Data` and `Initial Data`, have a look at the [Community Resources](../community/tkdodos-blog#9-placeholder-and-initial-data-in-react-query).

docs/src/pages/guides/queries.md

@@ -92,3 +92,6 @@ function Todos() {
   )
 }
 ```
+## 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).

docs/src/pages/guides/query-keys.md

@@ -5,7 +5,7 @@ title: Query Keys
 
 At its core, React Query manages query caching for you based on query keys. Query keys can be as simple as a string, or as complex as an array of many strings and nested objects. As long as the query key is serializable, and **unique to the query's data**, you can use it!
 
-### String-Only Query Keys
+## String-Only Query Keys
 
 The simplest form of a key is actually not an array, but an individual string. When a string query key is passed, it is converted to an array internally with the string as the only item in the query key. This format is useful for:
 
@@ -20,7 +20,7 @@ useQuery('todos', ...) // queryKey === ['todos']
 useQuery('somethingSpecial', ...) // queryKey === ['somethingSpecial']
 ```
 
-### Array Keys
+## Array Keys
 
 When a query needs more information to uniquely describe its data, you can use an array with a string and any number of serializable objects to describe it. This is useful for:
 
@@ -43,7 +43,7 @@ useQuery(['todos', { type: 'done' }], ...)
 // queryKey === ['todos', { type: 'done' }]
 ```
 
-### Query Keys are hashed deterministically!
+## Query Keys are hashed deterministically!
 
 This means that no matter the order of keys in objects, all of the following queries are considered equal:
 
@@ -70,3 +70,8 @@ function Todos({ todoId }) {
   const result = useQuery(['todos', todoId], () => fetchTodoById(todoId))
 }
 ```
+
+## 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) from
+the Community Resources.

docs/src/pages/guides/testing.md

@@ -177,3 +177,7 @@ expect(result.current.data.pages).toStrictEqual([
 
 expectation.done();
 ```
+## 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
+the Community Resources.