feat(codemod): add codemod that replaces the react-query import specifiers (#3801)

* feat(codemod): add codemod that replaces the react-query import specifiers

* feat(codemod): add codemod that replaces the react-query import specifiers

update migration docs

* feat(codemod): add codemod that replaces the react-query import specifiers

re-add yarn installation instructions

Author: TkDodo

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!
 
@@ -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/installation.md

@@ -11,6 +11,8 @@ 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.

packages/react-query/codemods/v4/__testfixtures__/replace-import-specifier.input.tsx

@@ -0,0 +1,10 @@
+// React Query
+import { useQuery, useQueryClient } from 'react-query'
+import { useQuery as RenamedUseQuery, useQueryClient as RenamedUseQueryClient } from 'react-query'
+import DefaultReactQuery from 'react-query'
+import * as NamespacedReactQuery from 'react-query'
+// Devtools
+import { ReactQueryDevtools } from 'react-query/devtools'
+import { ReactQueryDevtools as RenamedReactQueryDevtools } from 'react-query/devtools'
+import DefaultReactQueryDevtools from 'react-query/devtools'
+import * as NamespacedReactQueryDevtools from 'react-query/devtools'

packages/react-query/codemods/v4/__testfixtures__/replace-import-specifier.output.tsx

@@ -0,0 +1,10 @@
+// React Query
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { useQuery as RenamedUseQuery, useQueryClient as RenamedUseQueryClient } from '@tanstack/react-query'
+import DefaultReactQuery from '@tanstack/react-query'
+import * as NamespacedReactQuery from '@tanstack/react-query'
+// Devtools
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+import { ReactQueryDevtools as RenamedReactQueryDevtools } from '@tanstack/react-query-devtools'
+import DefaultReactQueryDevtools from '@tanstack/react-query-devtools'
+import * as NamespacedReactQueryDevtools from '@tanstack/react-query-devtools'

packages/react-query/codemods/v4/__tests__/replace-import-specifier.test.js

@@ -0,0 +1,14 @@
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const defineTest = require('jscodeshift/dist/testUtils').defineTest
+
+jest.autoMockOff()
+
+defineTest(
+  __dirname,
+  'replace-import-specifier',
+  null,
+  'replace-import-specifier',
+  {
+    parser: 'tsx',
+  },
+)

packages/react-query/codemods/v4/replace-import-specifier.js

@@ -0,0 +1,25 @@
+module.exports = (file, api) => {
+  const jscodeshift = api.jscodeshift
+  const root = jscodeshift(file.source)
+
+  const replacements = [
+    { from: 'react-query', to: '@tanstack/react-query' },
+    { from: 'react-query/devtools', to: '@tanstack/react-query-devtools' },
+  ]
+
+  replacements.forEach(({ from, to }) => {
+    root
+      .find(jscodeshift.ImportDeclaration, {
+        source: {
+          value: from,
+        },
+      })
+      .replaceWith(({ node }) => {
+        node.source.value = to
+
+        return node
+      })
+  })
+
+  return root.toSource({ quote: 'single' })
+}