Merge branch 'beta' of https://github.com/TanStack/query into feature/react-dom-dep

Author: duarten

docs/config.json

@@ -302,8 +302,8 @@
           "to": "plugins/persistQueryClient"
         },
         {
-          "label": "createWebStoragePersister",
-          "to": "plugins/createWebStoragePersister"
+          "label": "createSyncStoragePersister",
+          "to": "plugins/createSyncStoragePersister"
         },
         {
           "label": "createAsyncStoragePersister",

docs/devtools.md

@@ -15,6 +15,8 @@ The devtools are a separate package that you need to install:
 
 ```bash
 $ npm i @tanstack/react-query-devtools
+# or
+$ yarn add @tanstack/react-query-devtools
 ```
 
 You can import the devtools like this:

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

@@ -5,6 +5,8 @@ title: Migrating to React Query 4
 
 ## Breaking Changes
 
+v4 is a major version, so there are some breaking changes to be aware of:
+
 ### react-query is now @tanstack/react-query
 
 ```diff
@@ -15,6 +17,32 @@ title: Migrating to React Query 4
 + import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 ```
 
+#### Codemod
+
+To make this migration easier, v4 comes with a codemod.
+
+> The codemod is a best efforts attempt to help you migrate the breaking change. Please review the generated code thoroughly! Also, there are edge cases that cannot be found by the code mod, so please keep an eye on the log output.
+
+You can easily apply it by using one (or both) of the following commands:
+
+If you want to run it against `.js` or `.jsx` files, please use the command below:
+
+```
+npx jscodeshift --extensions=js,jsx --transform=./node_modules/@tanstack/react-query/codemods/v4/replace-import-specifier.js ./path/to/src/
+```
+
+If you want to run it against `.ts` or `.tsx` files, please use the command below:
+
+```
+npx jscodeshift --extensions=ts,tsx --parser=tsx --transform=./node_modules/@tanstack/react-query/codemods/v4/replace-import-specifier.js ./path/to/src/
+```
+
+Please note in the case of `TypeScript` you need to use `tsx` as the parser; otherwise, the codemod won't be applied properly!
+
+**Note:** Applying the codemod might break your code formatting, so please don't forget to run `prettier` and/or `eslint` after you've applied the codemod!
+
+**Note:** The codemod will _only_ change the imports - you still have to install the separate devtools package manually.
+
 ### Query Keys (and Mutation Keys) need to be an Array
 
 In v3, Query and Mutation Keys could be a String or an Array. Internally, React Query has always worked with Array Keys only, and we've sometimes exposed this to consumers. For example, in the `queryFn`, you would always get the key as an Array to make working with [Default Query Functions](./default-query-function) easier.
@@ -48,7 +76,7 @@ If you want to run it against `.ts` or `.tsx` files, please use the command belo
 npx jscodeshift --extensions=ts,tsx --parser=tsx --transform=./node_modules/@tanstack/react-query/codemods/v4/key-transformation.js ./path/to/src/
 ```
 
-Please note in the case of `TypeScript` you need to use `tsx` as the parser otherwise, the codemod won't be applied properly!
+Please note in the case of `TypeScript` you need to use `tsx` as the parser; otherwise, the codemod won't be applied properly!
 
 **Note:** Applying the codemod might break your code formatting, so please don't forget to run `prettier` and/or `eslint` after you've applied the codemod!
 
@@ -211,7 +239,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 [`createWebStoragePersister`](/plugins/createWebStoragePersister) 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:
 
@@ -221,7 +249,7 @@ Since these plugins are no longer experimental, their import paths have also bee
 - import { createAsyncStoragePersistor } from 'react-query/createAsyncStoragePersistor-experimental'
 
 + import { persistQueryClient } from '@tanstack/react-query-persist-client'
-+ import { createWebStoragePersister } from '@tanstack/query-sync-storage-persister'
++ import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
 + import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
 ```
 
@@ -335,6 +363,12 @@ If you were importing anything from `'react-query/react'` directly in your proje
 
 ## New Features 🚀
 
+v4 comes with an awesome set of new features:
+
+### Support for React 18
+
+React 18 was released earlier this year, and v4 now has first class support for it and the new concurrent features it brings.
+
 ### Proper offline support
 
 In v3, React Query has always fired off queries and mutations, but then taken the assumption that if you want to retry it, you need to be connected to the internet. This has led to several confusing situations:

docs/guides/mutations.md

@@ -151,7 +151,7 @@ useMutation(addTodo, {
 })
 ```
 
-You might find that you want to **trigger additional callbacks** than the ones defined on `useMutation` when calling `mutate`. This can be used to trigger component-specific side effects. To do that, you can provide any of the same callback options to the `mutate` function after your mutation variable. Supported overrides include: `onSuccess`, `onError` and `onSettled`. Please keep in mind that those additional callbacks won't run if your component unmounts _before_ the mutation finishes.
+You might find that you want to **trigger additional callbacks** beyond the ones defined on `useMutation` when calling `mutate`. This can be used to trigger component-specific side effects. To do that, you can provide any of the same callback options to the `mutate` function after your mutation variable. Supported overrides include: `onSuccess`, `onError` and `onSettled`. Please keep in mind that those additional callbacks won't run if your component unmounts _before_ the mutation finishes.
 
 ```js
 useMutation(addTodo, {
@@ -182,7 +182,7 @@ mutate(todo, {
 ### Consecutive mutations
 There is a slight difference in handling `onSuccess`, `onError` and `onSettled` callbacks when it comes to consecutive mutations. When passed to the `mutate` function, they will be fired up only _once_ and only if the component is still mounted.  This is due to the fact that mutation observer is removed and resubscribed every time when the `mutate` function is called. On the contrary, `useMutation` handlers execute for each `mutate` call.
 
-> Be aware that most likely, `mutationFn` passed to `useMutation` is ansynchronous. In that case, the order in which mutations are fulfilled may differ from the order of `mutate` function calls.
+> Be aware that most likely, `mutationFn` passed to `useMutation` is asynchronous. In that case, the order in which mutations are fulfilled may differ from the order of `mutate` function calls.
 
 ```js
 useMutation(addTodo, {
@@ -286,7 +286,7 @@ If you persist offline mutations with the [persistQueryClient plugin](../plugins
 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 triggeres the mutation might not be mounted, so calling `resumePausedMutations` might yield an error: `No mutationFn found`.
 
 ```js
-const persister = createWebStoragePersister({
+const persister = createSyncStoragePersister({
   storage: window.localStorage,
 })
 const queryClient = new QueryClient({

docs/guides/ssr.md

@@ -111,7 +111,7 @@ As demonstrated, it's fine to prefetch some queries and let others fetch on the
 
 There's a catch if you're using [Next.js' rewrites feature](https://nextjs.org/docs/api-reference/next.config.js/rewrites) together with [Automatic Static Optimization](https://nextjs.org/docs/advanced-features/automatic-static-optimization) or `getStaticProps`: It will cause a second hydration by React Query. That's because [Next.js needs to ensure that they parse the rewrites](https://nextjs.org/docs/api-reference/next.config.js/rewrites#rewrite-parameters) on the client and collect any params after hydration so that they can be provided in `router.query`.
 
-The result is missing referential equality for all the hydration data, which for example triggers whereever your data is used as props of components or in the dependency array of `useEffect`s/`useMemo`s.
+The result is missing referential equality for all the hydration data, which for example triggers wherever your data is used as props of components or in the dependency array of `useEffect`s/`useMemo`s.
 
 ## Using Other Frameworks or Custom SSR Frameworks
 

docs/installation.md

@@ -11,11 +11,13 @@ or a good ol' `<script>` via
 
 ```bash
 $ npm i @tanstack/react-query
+# or
+$ yarn add @tanstack/react-query
 ```
 
 React Query is compatible with React v16.8+ and works with ReactDOM and React Native.
 
-> Wanna give it a spin before you download? Try out the [simple](/docs/examples/simple) or [basic](/docs/examples/basic) examples!
+> Wanna give it a spin before you download? Try out the [simple](/query/v4/docs/examples/react/simple) or [basic](/query/v4/docs/examples/react/basic) examples!
 
 ### CDN
 

docs/plugins/createAsyncStoragePersister.md

@@ -39,7 +39,7 @@ persistQueryClient({
 
 ## Retries
 
-Retries work the same as for a [WebStoragePersister](./createWebStoragePersister), except that they can also be asynchronous. You can also use all the predefined retry handlers.
+Retries work the same as for a [SyncStoragePersister](./createSyncStoragePersister), except that they can also be asynchronous. You can also use all the predefined retry handlers.
 
 ## API
 

docs/plugins/createWebStoragePersister.md renamed to docs/plugins/createSyncStoragePersister.md

@@ -1,21 +1,21 @@
 ---
-id: createWebStoragePersister
-title: createWebStoragePersister
+id: createSyncStoragePersister
+title: createSyncStoragePersister
 ---
 
 ## Installation
 
-This utility comes packaged with `react-query` and is available under the `react-query/createWebStoragePersister` import.
+This utility comes as a separate package and is available under the `'@tanstack/query-sync-storage-persister'` import.
 
 ## Usage
 
-- Import the `createWebStoragePersister` function
-- Create a new webStoragePersister
+- Import the `createSyncStoragePersister` function
+- Create a new syncStoragePersister
 - Pass it to the [`persistQueryClient`](./persistQueryClient) function
 
 ```ts
-import { persistQueryClient } from 'react-query/persistQueryClient'
-import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
+import { persistQueryClient } from '@tanstack/react-query-persist-client'
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -25,8 +25,8 @@ const queryClient = new QueryClient({
   },
 })
 
-const localStoragePersister = createWebStoragePersister({ storage: window.localStorage })
-// const sessionStoragePersister = createWebStoragePersister({ storage: window.sessionStorage })
+const localStoragePersister = createSyncStoragePersister({ storage: window.localStorage })
+// const sessionStoragePersister = createSyncStoragePersister({ storage: window.sessionStorage })
 
 persistQueryClient({
   queryClient,
@@ -56,26 +56,26 @@ Per default, no retry will occur. You can use one of the predefined strategies t
   - will return a new `PersistedClient` with the oldest query removed.
 
 ```js
-const localStoragePersister = createWebStoragePersister({
+const localStoragePersister = createSyncStoragePersister({
   storage: window.localStorage,
   retry: removeOldestQuery
 })
 ```
 
 ## API
 
-### `createWebStoragePersister`
+### `createSyncStoragePersister`
 
-Call this function to create a webStoragePersister that you can use later with `persistQueryClient`.
+Call this function to create a syncStoragePersister that you can use later with `persistQueryClient`.
 
 ```js
-createWebStoragePersister(options: CreateWebStoragePersisterOptions)
+createSyncStoragePersister(options: CreateSyncStoragePersisterOptions)
 ```
 
 ### `Options`
 
 ```ts
-interface CreateWebStoragePersisterOptions {
+interface CreateSyncStoragePersisterOptions {
   /** The storage client used for setting an retrieving items from cache (window.localStorage or window.sessionStorage) */
   storage: Storage
   /** The key to use when storing the cache */
@@ -109,16 +109,16 @@ If you need to store more data in `localStorage`, you can override the `serializ
 
 ```js
 import { QueryClient } from '@tanstack/react-query';
-import { persistQueryClient } from 'react-query/persistQueryClient'
-import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
+import { persistQueryClient } from '@tanstack/react-query-persist-client'
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
 
 import { compress, decompress } from 'lz-string';
 
 const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: Infinity } } });
 
 persistQueryClient({
   queryClient: connectionsQueryClient,
-  persistor: createWebStoragePersister({
+  persistor: createSyncStoragePersister({
     storage: window.localStorage,
     serialize: data => compress(JSON.stringify(data)),
     deserialize: data => JSON.parse(decompress(data)),

docs/plugins/persistQueryClient.md

@@ -7,7 +7,7 @@ This is set of utilities for interacting with "persisters" which save your query
 
 ## Build Persisters
 
-- [createWebStoragePersister](/plugins/createWebStoragePersister)
+- [createSyncStoragePersister](/plugins/createSyncStoragePersister)
 - [createAsyncStoragePersister](/plugins/createAsyncStoragePersister)
 - [create a custom persister](#persisters)
 
@@ -57,7 +57,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.
-- `createWebStoragePersister` 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.
+- `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.
 
@@ -181,8 +181,8 @@ For this use-case, you can use the `PersistQueryClientProvider`. It will make su
 
 ```jsx
 
-import { PersistQueryClientProvider } from 'react-query/persistQueryClient'
-import { createWebStoragePersister } from 'react-query/createWebStoragePersister'
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -192,7 +192,7 @@ const queryClient = new QueryClient({
   },
 })
 
-const persister = createWebStoragePersister({
+const persister = createSyncStoragePersister({
   storage: window.localStorage,
 })
 

docs/react-native.md

@@ -20,7 +20,7 @@ import { onlineManager } from '@tanstack/react-query'
 
 onlineManager.setEventListener(setOnline => {
   return NetInfo.addEventListener(state => {
-    setOnline(state.isConnected)
+    setOnline(!!state.isConnected)
   })
 })
 ```