Merge pull request #320 from codemod-com/codemods-v3

Add react 19 codemods and recommend `codemod` command

Author: rickhanlonii

.eslintrc.js

@@ -1,5 +1,5 @@
 module.exports = {
-  parser: 'babel-eslint',
+  parser: '@typescript-eslint/parser',
 
   extends: './node_modules/fbjs-scripts/eslint/.eslintrc.js',
 

LEGACY.md

@@ -0,0 +1,279 @@
+## Legacy `react-codemod`
+
+All codemods in this repo can be run using the legacy `react-codemod` command, which runs the codemods via jscodeshift directly.
+
+### Usage
+
+We recommend using the [`codemod`](github.com/reactjs/react-codemod) command for improved experience and support.
+
+To use `react-codemod` directly:
+
+`npx react-codemod <transform> <path> [...options]`
+* `transform` - name of transform, see available transforms below.
+* `path` - files or directory to transform
+* use the `--dry` option for a dry-run and use `--print` to print the output for comparison
+
+This will start an interactive wizard, and then run the specified transform.
+
+### Included Transforms
+
+#### `remove-context-provider`
+
+Converts `Context.Provider` JSX opening and closing elements into `Context`.
+
+```sh
+npx react-codemod remove-context-provider <path>
+```
+
+#### `remove-forward-ref`
+
+Removes usages of `forwardRef`.
+
+```sh
+npx react-codemod remove-forward-ref <path>
+```
+
+#### `use-context-hook`
+
+```sh
+npx react-codemod use-context-hook <path>
+```
+
+#### `replace-act-import`
+
+```sh
+npx react-codemod replace-act-import <path>
+```
+
+#### `replace-string-ref`
+
+Replaces deprecated string refs with callback refs.
+
+```sh
+npx react-codemod replace-string-ref <path>
+```
+
+#### `replace-use-form-state`
+
+Replaces usages of useFormState() to use useActionState().
+
+```sh
+npx react-codemod replace-use-form-state <path>
+```
+
+#### `replace-reactdom-render`
+
+Replaces usages of ReactDom.render() with createRoot(node).render().
+
+```sh
+npx react-codemod replace-reactdom-render <path>
+```
+
+#### `create-element-to-jsx`
+
+Converts calls to `React.createElement` into JSX elements.
+
+```sh
+npx react-codemod create-element-to-jsx <path>
+```
+
+#### `error-boundaries`
+
+Renames the experimental `unstable_handleError` lifecycle hook to `componentDidCatch`.
+
+```sh
+npx react-codemod error-boundaries <path>
+```
+
+#### `findDOMNode`
+
+Updates `this.getDOMNode()` or `this.refs.foo.getDOMNode()` calls inside of
+`React.createClass` components to `React.findDOMNode(foo)`. Note that it will
+only look at code inside of `React.createClass` calls and only update calls on
+the component instance or its refs. You can use this script to update most calls
+to `getDOMNode` and then manually go through the remaining calls.
+
+```sh
+npx react-codemod findDOMNode <path>
+```
+
+#### `manual-bind-to-arrow`
+
+Converts manual function bindings in a class (e.g., `this.f = this.f.bind(this)`) to arrow property initializer functions (e.g., `f = () => {}`).
+
+```sh
+npx react-codemod manual-bind-to-arrow <path>
+```
+
+#### `pure-component`
+
+Converts ES6 classes that only have a render method, only have safe properties
+(statics and props), and do not have refs to Functional Components.
+
+The wizard will ask for 2 options -
+
+* **Use arrow functions?**: converts to arrow function. Converts to `function` by default.
+* **Destructure props?**: will destructure props in the argument where it is safe to do so.
+
+```sh
+npx react-codemod pure-component <path>
+```
+
+#### `pure-render-mixin`
+
+Removes `PureRenderMixin` and inlines `shouldComponentUpdate` so that the ES2015
+class transform can pick up the React component and turn it into an ES2015
+class. NOTE: This currently only works if you are using the master version
+(>0.13.1) of React as it is using `React.addons.shallowCompare`
+
+```sh
+npx react-codemod pure-render-mixin <path>
+```
+
+* The wizard will ask to optionally override `mixin-name`, and look for it
+  instead of `PureRenderMixin`. Note that it is not possible to use a
+  namespaced name for the mixin. `mixins: [React.addons.PureRenderMixin]` will
+  not currently work.
+
+#### `React-PropTypes-to-prop-types`
+
+Replaces `React.PropTypes` references with `prop-types` and adds the appropriate `import` or `require` statement. This codemod is intended for React 15.5+.
+
+```sh
+npx react-codemod React-PropTypes-to-prop-types <path>
+```
+
+* In addition to running the above codemod you will also need to install the `prop-types` NPM package.
+
+#### `rename-unsafe-lifecycles`
+
+Adds `UNSAFE_` prefix for deprecated lifecycle hooks. (For more information about this codemod, see [React RFC #6](https://github.com/reactjs/rfcs/pull/6))
+
+```sh
+npx react-codemod rename-unsafe-lifecycles <path>
+```
+
+#### `react-to-react-dom`
+
+Updates code for the split of the `react` and `react-dom` packages (e.g.,
+`React.render` to `ReactDOM.render`). It looks for `require('react')` and
+replaces the appropriate property accesses using `require('react-dom')`. It does
+not support ES6 modules or other non-CommonJS systems. We recommend performing
+the `findDOMNode` conversion first.
+
+
+```sh
+npx react-codemod react-to-react-dom <path>
+```
+
+* After running the automated codemod, you may want to run a regex-based
+  find-and-replace to remove extra whitespace between the added requires, such
+  as `codemod.py -m -d src --extensions js '(var
+  React\s*=\s*require\(.react.\);)\n\n(\s*var ReactDOM)' '\1\n\2'` using
+  https://github.com/facebook/codemod.
+
+#### `React-DOM-to-react-dom-factories`
+
+Converts calls like `React.DOM.div(...)` to `React.createElement('div', ...)`.
+
+```sh
+npx react-codemod React-DOM-to-react-dom-factories <path>
+```
+
+#### `ReactNative-View-propTypes`
+
+Replaces `View.propTypes` references with `ViewPropTypes` and adds the appropriate `import` or `require` statement. This codemod is intended for ReactNative 44+.
+
+```sh
+npx react-codemod ReactNative-View-propTypes <path>
+```
+
+#### `sort-comp`
+
+Reorders React component methods to match the [ESLint](http://eslint.org/)
+[react/sort-comp
+rule](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/sort-comp.md). (Defaults to ordering of the [Airbnb style
+guide](https://github.com/airbnb/javascript/blob/7684892951ef663e1c4e62ad57d662e9b2748b9e/packages/eslint-config-airbnb/rules/react.js#L122-L134).
+
+`react-codemod`:
+```sh
+npx react-codemod sort-comp <path>
+```
+
+#### `update-react-imports`
+
+[As of Babel 7.9.0](https://babeljs.io/blog/2020/03/16/7.9.0#a-new-jsx-transform-11154-https-githubcom-babel-babel-pull-11154), when using `runtime: automatic` in `@babel/preset-react` or `@babel/plugin-transform-react-jsx`, you will not need to explicitly import React for compiling jsx. This codemod removes the redundant import statements. It also converts default imports (`import React from 'react'`) to named imports (e.g. `import { useState } from 'react'`).
+
+The wizard will ask for 1 option -
+
+* **Destructure namespace imports as well?**: If chosen, *namespace* imports like `import * as React` will *also* be converted. By default, it's false, so only default imports (`import React`) are converted.
+
+```sh
+npx react-codemod update-react-imports <path>
+```
+
+### Explanation of the new ES2015 class transform with property initializers
+1. Determine if mixins are convertible. We only transform a `createClass` call to an ES6 class component when:
+- There are no mixins on the class, or
+- `options['pure-component']` is true, the `mixins` property is an array and it _only_ contains pure render mixin (the specific module name can be specified using `options['mixin-module-name']`, which defaults to `react-addons-pure-render-mixin`)
+2. Ignore components that:
+- Call deprecated APIs. This is very defensive, if the script finds any identifiers called `isMounted`, `getDOMNode`, `replaceProps`, `replaceState` or `setProps` it will skip the component
+- Explicitly call `this.getInitialState()` and/or `this.getDefaultProps()` since an ES6 class component will no longer have these methods
+- Use `arguments` in methods since arrow functions don't have `arguments`. Also please notice that `arguments` should be [very carefully used](https://github.com/petkaantonov/bluebird/wiki/Optimization-killers#3-managing-arguments) and it's generally better to switch to spread (`...args`) instead
+- Have inconvertible `getInitialState()`. Specifically if you have variable declarations like `var props = ...` and the right hand side is not `this.props` then we can't inline the state initialization in the `constructor` due to variable shadowing issues
+- Have non-primitive right hand side values (like `foo: getStuff()`) in the class spec
+3. Transform it to an ES6 class component
+1. Replace `var A = React.createClass(spec)` with `class A extends React.Component {spec}`. If a component uses pure render mixin and passes the mixins test (as described above), it will extend `React.PureComponent` instead
+   - Remove the `require`/`import` statement that imports pure render mixin when it's no longer being referenced
+2. Pull out all statics defined on `statics` plus the few special cased statics like `childContextTypes`, `contextTypes`, `displayName`, `getDefaultProps()`, and `propTypes` and transform them to `static` properties (`static propTypes = {...};`)
+   - If `getDefaultProps()` is simple (i.e. it only contains a return statement that returns something) it will be converted to a simple assignment (`static defaultProps = ...;`). Otherwise an IIFE (immediately-invoked function expression) will be created (`static defaultProps = function() { ... }();`). Note that this means that the function will be executed only a single time per app-lifetime. In practice this hasn't caused any issues — `getDefaultProps` should not contain any side-effects
+3. Transform `getInitialState()`
+   - If there's no `getInitialState()` or the `getInitialState()` function is simple (i.e., it only contains a return statement that returns something) then we don't need a constructor; `state` will be lifted to a property initializer (`state = ...;`)
+    - However, if the RHS of `return` contains references to `this` other than `this.props` and/or `this.context`, we can't be sure about what you'll need from `this`. We need to ensure that our property initializers' evaluation order is safe, so we defer `state`'s initialization by moving it all the way down until all other property initializers have been initialized
+      - If `getInitialState()` is not simple, we create a `constructor` and convert `getInitialState()` to an assignment to `this.state`
+    - `constructor` always have `props` as the first parameter
+    - We only put `context` as the second parameter when (one of) the following things happen in `getInitialState()`:
+        - It accesses `this.context`, or
+        - There's a direct method call `this.x()`, or
+        - `this` is referenced alone
+    - Rewrite accesses to `this.props` to `props` and accesses to `this.context` to `context` since the values will be passed as `constructor` arguments
+        - Remove _simple_ variable declarations like `var props = this.props;` and `var context = this.context`
+    - Rewrite top-level return statements (`return {...};`) to `this.state = {...}`
+        - Add `return;` after the assignment when the return statement is part of a control flow statement (not a direct child of `getInitialState()`'s body) and not in an inner function declaration
+4. Transform all non-lifecycle methods and fields to class property initializers (like `onClick = () => {};`). All your Flow annotations will be preserved
+   - It's actually not necessary to transform all methods to arrow functions (i.e., to bind them), but this behavior is the same as `createClass()` and we can make sure that we won't accidentally break stuff
+4. Generate Flow annotations from `propTypes` and put it on the class (this only happens when there's `/* @flow */` in your code and `options['flow']` is `true`)
+- Flow actually understands `propTypes` in `createClass` calls but not ES6 class components. Here the transformation logic is identical to [how](https://github.com/facebook/flow/blob/master/src/typing/statement.ml#L3526) Flow treats `propTypes`
+- Notice that Flow treats an optional propType as non-nullable
+    - For example, `foo: React.PropTypes.number` is valid when you pass `{}`, `{foo: null}`, or `{foo: undefined}` as props at **runtime**. However, when Flow infers type from a `createClass` call, only `{}` and `{foo: undefined}` are valid; `{foo: null}` is not. Thus the equivalent type annotation in Flow is actually `{foo?: number}`. The question mark on the left hand side indicates `{}` and `{foo: undefined}` are fine, but when `foo` is present it must be a `number`
+- For `propTypes` fields that can't be recognized by Flow, `$FlowFixMe` will be used
+5. `React.createClass` is no longer present in React 16. So, if a `createClass` call cannot be converted to a plain class, the script will fallback to using the `create-react-class` package.
+- Replaces `React.createClass` with `ReactCreateClass`.
+- Adds a `require` or `import` statement for `create-react-class`. The import style is inferred from the import style of the `react` import. The default module name can be overridden with the `--create-class-module-name` option.
+- Prunes the `react` import if there are no more references to it.
+
+
+## `react-codemod` options
+
+### jscodeshift options
+
+To pass more options directly to jscodeshift, use `--jscodeshift="..."`. For example:
+```sh
+npx react-codemod --jscodeshift="--run-in-band --verbose=2"
+```
+
+See all available options [here](https://github.com/facebook/jscodeshift#usage-cli).
+
+### Recast Options
+
+Options to [recast](https://github.com/benjamn/recast)'s printer can be provided
+through jscodeshift's `printOptions` command line argument
+
+```sh
+npx react-codemod <transform> <path> --jscodeshift="--printOptions='{\"quote\":\"double\"}'"
+```
+
+### `explicit-require=false`
+
+If you're not explicitly importing React in your files (eg: if you're loading React with a script tag), you should add `--explicit-require=false`.
+