From 5e15caa8b3e70e2ea34972f53862bb113fd32950 Mon Sep 17 00:00:00 2001 From: Joe Lencioni Date: Wed, 3 Feb 2016 20:50:38 -0800 Subject: [PATCH 1/6] Break up "Included Scripts" section with headings I found this wall of text a little difficult to parse. I think it works much better with some headings. While I was at it, I decided to wrap some long lines to be more consistent with the rest of this document. --- README.md | 50 +++++++++++++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 19499de1..6e290d0d 100644 --- a/README.md +++ b/README.md @@ -15,33 +15,43 @@ APIs. ### Included Scripts -`create-element-to-jsx` converts calls to `React.createElement` into JSX elements. +#### `create-element-to-jsx` + +Converts calls to `React.createElement` into JSX elements. * `jscodeshift -t react-codemod/transforms/create-element-to-jsx.js ` -`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. +#### `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. * `jscodeshift -t react-codemod/transforms/findDOMNode.js ` -`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. +#### `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. * `jscodeshift -t react-codemod/transforms/react-to-react-dom.js ` - * 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. + * 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. -`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` +#### `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` * `jscodeshift -t react-codemod/transforms/pure-render-mixin.js ` * If `--mixin-name=` is specified it will look for the specified name @@ -49,7 +59,9 @@ are using the master version (>0.13.1) of React as it is using namespaced name for the mixin. `mixins: [React.addons.PureRenderMixin]` will not currently work. -`class` transforms `React.createClass` calls into ES2015 classes. +#### `class` + +Transforms `React.createClass` calls into ES2015 classes. * `jscodeshift -t react-codemod/transforms/class.js ` * If `--no-super-class` is specified it will not extend From eedd08b2ea284c185740f58bcae3a1f8c9583598 Mon Sep 17 00:00:00 2001 From: Joe Lencioni Date: Wed, 3 Feb 2016 20:54:27 -0800 Subject: [PATCH 2/6] Sort "Included Scripts" alphabetically The alphabetical sorting is easy to understand, making it easier for people to find scripts that they are looking for and making it easier for future devs to know where to add new scripts. --- README.md | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6e290d0d..a38a6152 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,17 @@ APIs. ### Included Scripts +#### `class` + +Transforms `React.createClass` calls into ES2015 classes. + + * `jscodeshift -t react-codemod/transforms/class.js ` + * If `--no-super-class` is specified it will not extend + `React.Component` if `setState` and `forceUpdate` aren't being called in a + class. We do recommend always extending from `React.Component`, especially + if you are using or planning to use [Flow](http://flowtype.org/). Also make + sure you are not calling `setState` anywhere outside of your component. + #### `create-element-to-jsx` Converts calls to `React.createElement` into JSX elements. @@ -31,21 +42,6 @@ to `getDOMNode` and then manually go through the remaining calls. * `jscodeshift -t react-codemod/transforms/findDOMNode.js ` -#### `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. - - * `jscodeshift -t react-codemod/transforms/react-to-react-dom.js ` - * 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. - #### `pure-render-mixin` Removes `PureRenderMixin` and inlines `shouldComponentUpdate` so that the ES2015 @@ -59,16 +55,20 @@ class. NOTE: This currently only works if you are using the master version namespaced name for the mixin. `mixins: [React.addons.PureRenderMixin]` will not currently work. -#### `class` +#### `react-to-react-dom` -Transforms `React.createClass` calls into ES2015 classes. +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. - * `jscodeshift -t react-codemod/transforms/class.js ` - * If `--no-super-class` is specified it will not extend - `React.Component` if `setState` and `forceUpdate` aren't being called in a - class. We do recommend always extending from `React.Component`, especially - if you are using or planning to use [Flow](http://flowtype.org/). Also make - sure you are not calling `setState` anywhere outside of your component. + * `jscodeshift -t react-codemod/transforms/react-to-react-dom.js ` + * 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. These three scripts take an option `--no-explicit-require` if you don't have a `require('React')` statement in your code files and if you access React as a From 5603430401cea54e06e530c3d3329e18629194c6 Mon Sep 17 00:00:00 2001 From: Joe Lencioni Date: Wed, 3 Feb 2016 20:57:30 -0800 Subject: [PATCH 3/6] Remove mention of --no-explicit-require from readme This mentions "These three scripts" when there are four mentioned, and I am unable to find any references to `--no-explicit-require` in code, so I think this sentence is outdated and should be removed. Digging through history, it seems like this was brought over from 1c672cbb9f9 when code was imported from the React repo. --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index a38a6152..882a060d 100644 --- a/README.md +++ b/README.md @@ -70,10 +70,6 @@ the `findDOMNode` conversion first. React\s*=\s*require\(.react.\);)\n\n(\s*var ReactDOM)' '\1\n\2'` using https://github.com/facebook/codemod. -These three scripts take an option `--no-explicit-require` if you don't have a -`require('React')` statement in your code files and if you access React as a -global. - ### Explanation of the ES2015 class transform * Ignore components with calls to deprecated APIs. This is very defensive, if From af98aa47d95449c3245469c71df820c9ea76c8fb Mon Sep 17 00:00:00 2001 From: Joe Lencioni Date: Wed, 3 Feb 2016 21:02:50 -0800 Subject: [PATCH 4/6] Add sort-comp section to readme This useful transform was undocumented, so I decided to copy the comment from the top of the file into the readme. This will help make it more discoverable. --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 882a060d..4347ff86 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,16 @@ the `findDOMNode` conversion first. React\s*=\s*require\(.react.\);)\n\n(\s*var ReactDOM)' '\1\n\2'` using https://github.com/facebook/codemod. +#### `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), +specifically with the [tighter constraints of the Airbnb style +guide](https://github.com/airbnb/javascript/blob/6c89f958/packages/eslint-config-airbnb/rules/react.js#L47-L57). + + * `jscodeshift -t react-codemod/transforms/sort-comp.js ` + ### Explanation of the ES2015 class transform * Ignore components with calls to deprecated APIs. This is very defensive, if From 66f7ed510e6bebed49ea4e4044cd04e7e26de006 Mon Sep 17 00:00:00 2001 From: Joe Lencioni Date: Wed, 3 Feb 2016 21:05:30 -0800 Subject: [PATCH 5/6] Document pure-component transform in readme This transform exists, but was not mentioned in the readme. I haven't taken the time to look at it and understand what it does, so I didn't write a description, but I figure that something is better than nothing. --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 4347ff86..4ff8d15e 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,10 @@ to `getDOMNode` and then manually go through the remaining calls. * `jscodeshift -t react-codemod/transforms/findDOMNode.js ` +#### `pure-component` + + * `jscodeshift -t react-codemod/transforms/pure-component.js ` + #### `pure-render-mixin` Removes `PureRenderMixin` and inlines `shouldComponentUpdate` so that the ES2015 From bacc720c91f50e8d79c4dca880f06e1ab9a0b1ad Mon Sep 17 00:00:00 2001 From: Joe Lencioni Date: Wed, 3 Feb 2016 21:08:41 -0800 Subject: [PATCH 6/6] Use fenced code blocks for some examples This will give us a little bit of syntax highlighting and cut down on the number of bullet points on the page. My goal here is to make this document easier to read. --- README.md | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 4ff8d15e..c390f8b9 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,10 @@ APIs. Transforms `React.createClass` calls into ES2015 classes. - * `jscodeshift -t react-codemod/transforms/class.js ` +```sh +jscodeshift -t react-codemod/transforms/class.js +``` + * If `--no-super-class` is specified it will not extend `React.Component` if `setState` and `forceUpdate` aren't being called in a class. We do recommend always extending from `React.Component`, especially @@ -30,7 +33,9 @@ Transforms `React.createClass` calls into ES2015 classes. Converts calls to `React.createElement` into JSX elements. - * `jscodeshift -t react-codemod/transforms/create-element-to-jsx.js ` +```sh +jscodeshift -t react-codemod/transforms/create-element-to-jsx.js +``` #### `findDOMNode` @@ -40,11 +45,15 @@ 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. - * `jscodeshift -t react-codemod/transforms/findDOMNode.js ` +```sh +jscodeshift -t react-codemod/transforms/findDOMNode.js +``` #### `pure-component` - * `jscodeshift -t react-codemod/transforms/pure-component.js ` +```sh +jscodeshift -t react-codemod/transforms/pure-component.js +``` #### `pure-render-mixin` @@ -53,7 +62,10 @@ 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` - * `jscodeshift -t react-codemod/transforms/pure-render-mixin.js ` +```sh +jscodeshift -t react-codemod/transforms/pure-render-mixin.js +``` + * If `--mixin-name=` is specified it will look for the specified name instead of `PureRenderMixin`. Note that it is not possible to use a namespaced name for the mixin. `mixins: [React.addons.PureRenderMixin]` will @@ -67,7 +79,10 @@ 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. - * `jscodeshift -t react-codemod/transforms/react-to-react-dom.js ` +```sh +jscodeshift -t react-codemod/transforms/react-to-react-dom.js +``` + * 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 @@ -82,7 +97,9 @@ rule](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/so specifically with the [tighter constraints of the Airbnb style guide](https://github.com/airbnb/javascript/blob/6c89f958/packages/eslint-config-airbnb/rules/react.js#L47-L57). - * `jscodeshift -t react-codemod/transforms/sort-comp.js ` +```sh +jscodeshift -t react-codemod/transforms/sort-comp.js +``` ### Explanation of the ES2015 class transform @@ -118,6 +135,7 @@ guide](https://github.com/airbnb/javascript/blob/6c89f958/packages/eslint-config class. The constructor logic is as follows: + * Call `super(props, context)` if the base class needs to be extended. * Bind all functions that are passed around, like `this.foo = this.foo.bind(this)` @@ -134,4 +152,6 @@ The constructor logic is as follows: Options to [recast](https://github.com/benjamn/recast)'s printer can be provided through the `printOptions` command line argument - * `jscodeshift -t transform.js --printOptions='{"quote":"double"}'` +```sh +jscodeshift -t transform.js --printOptions='{"quote":"double"}' +```