|
| 1 | +<div align="center"> |
| 2 | + |
| 3 | +<a href="https://github.com/typescript-cheatsheets/react-typescript-cheatsheet/issues/81"> |
| 4 | + <img |
| 5 | + height="90" |
| 6 | + width="90" |
| 7 | + alt="react + ts logo" |
| 8 | + src="https://user-images.githubusercontent.com/6764957/53868378-2b51fc80-3fb3-11e9-9cee-0277efe8a927.png" |
| 9 | + align="left" |
| 10 | + /> |
| 11 | +</a> |
| 12 | + |
| 13 | +<p>Cheatsheets para desarrolladores expertos en React que comienzan con TypeScript</p> |
| 14 | + |
| 15 | +[**Básico**](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet#basic-cheatsheet-table-of-contents) | |
| 16 | +[**Avanzado**](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet-es/blob/master/AVANZADO.md) | |
| 17 | +[**Migrando**](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet/blob/master/MIGRATING.md) | |
| 18 | +[**HOC**](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet/blob/master/HOC.md) | |
| 19 | +[**Inglés**](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet) | |
| 20 | +[**中文翻译**](https://github.com/fi3ework/blog/tree/master/react-typescript-cheatsheet-cn) | |
| 21 | +[Contribuir](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet-es/blob/master/CONTRIBUYENDO.md) | |
| 22 | +[Preguntas](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet-es/issues/new) |
| 23 | + |
| 24 | +</div> |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +# Migrando (a TypeScript) Cheatsheet |
| 29 | + |
| 30 | +This Cheatsheet collates advice and utilities from real case studies of teams moving significant codebases from plain JS or Flow over to TypeScript. It makes no attempt to _convince_ people to do so, but we do collect what few statistics companies offer up after their conversion experience. |
| 31 | + |
| 32 | +> ⚠️ This Cheatsheet is extremely new and could use all the help we can get. Solid advice, results, and up to date content all welcome. |
| 33 | +
|
| 34 | +## Prerequsite |
| 35 | + |
| 36 | +Read [TypeScript's official Guide for migrating from JS](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) and you should already be familiar with their [React conversion guide](https://github.com/Microsoft/TypeScript-React-Conversion-Guide#typescript-react-conversion-guide). |
| 37 | + |
| 38 | +## General Conversion approaches |
| 39 | + |
| 40 | +- Level 0: Don't use TypeScript, use JSDoc |
| 41 | + - See our [JSDoc section](#JSDoc) |
| 42 | +- Level 1A: Majority JavaScript, increasingly strict TypeScript |
| 43 | + - as recommended by [official TS guide](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) |
| 44 | + - use `allowJS` (Experiences: [clayallsop][clayallsop], [pleo][pleo]) |
| 45 | +- Level 1B: Total rename to TypeScript from the start |
| 46 | + - "[Just rename all .js files to .ts](https://twitter.com/jamonholmgren/status/1089241726303199232)"? |
| 47 | + - use the loosest, bare minimum settings to start with |
| 48 | +- Level 2: Strict TypeScript |
| 49 | + - use Microsoft's [`dts-gen`](https://github.com/Microsoft/dts-gen) to generate `.d.ts` files for your untyped files. [This SO answer](https://stackoverflow.com/questions/12687779/how-do-you-produce-a-d-ts-typings-definition-file-from-an-existing-javascript) has more on the topic. |
| 50 | + - use `declare` keyword for ambient declarations - see [declaration merging](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet#troubleshooting-handbook-bugs-in-official-typings) to patch library declarations inline |
| 51 | + |
| 52 | +Misc tips/approaches successful companies have taken |
| 53 | + |
| 54 | +- `@ts-ignore` on compiler errors for libraries with no typedefs |
| 55 | +- pick ESLint over TSLint (source: [ESLint](https://eslint.org/blog/2019/01/future-typescript-eslint) and [TS Roadmap](https://github.com/Microsoft/TypeScript/issues/29288)). [You can convert TSlint to ESlint with this tool](https://github.com/typescript-eslint/tslint-to-eslint-config). |
| 56 | +- New code must always be written in TypeScript. No exceptions. For existing code: If your task requires you to change JavaScript code, you need to rewrite it. (Source: [Hootsuite][hootsuite]) |
| 57 | + |
| 58 | +<details> |
| 59 | +<summary> |
| 60 | +<b> |
| 61 | +Webpack tips |
| 62 | +</b> |
| 63 | +</summary> |
| 64 | + |
| 65 | +- webpack loader: `awesome-typescript-loader` vs `ts-loader`? (there is some disagreement in community about this - but read [awesome's point of view](https://github.com/s-panferov/awesome-typescript-loader#differences-between-ts-loader)) |
| 66 | +- Webpack config: |
| 67 | + |
| 68 | +``` |
| 69 | +module.exports = { |
| 70 | +
|
| 71 | +resolve: { |
| 72 | +- extensions: ['.js', '.jsx'] |
| 73 | ++ extensions: ['.ts', '.tsx', '.js', '.jsx'] |
| 74 | +}, |
| 75 | +
|
| 76 | +// Source maps support ('inline-source-map' also works) |
| 77 | +devtool: 'source-map', |
| 78 | +
|
| 79 | +// Add the loader for .ts files. |
| 80 | +module: { |
| 81 | + loaders: [{ |
| 82 | +- test: /\.jsx?$/, |
| 83 | +- loader: 'babel-loader', |
| 84 | +- exclude: [/node_modules/], |
| 85 | ++ test: /\.(t|j)sx?$/, |
| 86 | ++ loader: ['awesome-typescript-loader?module=es6'], |
| 87 | ++ exclude: [/node_modules/] |
| 88 | ++ }, { |
| 89 | ++ test: /\.js$/, |
| 90 | ++ loader: 'source-map-loader', |
| 91 | ++ enforce: 'pre' |
| 92 | + }] |
| 93 | +} |
| 94 | +}; |
| 95 | +``` |
| 96 | + |
| 97 | +Special note on `ts-loader` and 3rd party libraries: https://twitter.com/acemarke/status/1091150384184229888 |
| 98 | + |
| 99 | +</details> |
| 100 | + |
| 101 | +## JSDoc |
| 102 | + |
| 103 | +- https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript |
| 104 | +- webpack's codebase uses JSDoc with linting by TS https://twitter.com/TheLarkInn/status/984479953927327744 (some crazy hack: https://twitter.com/thelarkinn/status/996475530944823296) |
| 105 | + |
| 106 | +Problems to be aware of: |
| 107 | + |
| 108 | +- `object` is converted to `any` for some reason. |
| 109 | +- If you have an error in the jsdoc, you get no warning/error. TS just silently doesn't type annotate the function. |
| 110 | +- [casting can be verbose](https://twitter.com/bahmutov/status/1089229349637754880) |
| 111 | + |
| 112 | +(_thanks [Gil Tayar](https://twitter.com/giltayar/status/1089228919260221441) and [Gleb Bahmutov](https://twitter.com/bahmutov/status/1089229196247908353) for sharing above commentary_) |
| 113 | + |
| 114 | +## From JS |
| 115 | + |
| 116 | +### Automated JS to TS Conversion |
| 117 | + |
| 118 | +- [TypeStat](https://github.com/JoshuaKGoldberg/TypeStat) ([used by Codecademy](https://mobile.twitter.com/JoshuaKGoldberg/status/1159090281314160640)) |
| 119 | +- [TypeWiz](https://github.com/urish/typewiz) |
| 120 | +- [js-to-ts-converter](https://github.com/gregjacobs/js-to-ts-converter) |
| 121 | + |
| 122 | +### Manual JS to TS Conversion |
| 123 | + |
| 124 | +the "Just Renaming" strategy |
| 125 | + |
| 126 | +- OSX/Linux: `find src -name "*.js" -exec sh -c 'mv"$0" "${0%.js}.tsx"' {} \;` |
| 127 | + |
| 128 | +You can either load typescript files with webpack, or use the `tsc` compiler to compile your TS files to JS side by side. The basic `tsconfig.json` is: |
| 129 | + |
| 130 | +```json |
| 131 | +{ |
| 132 | + "compilerOptions": { |
| 133 | + "allowJs": true |
| 134 | + } |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +Then you will want to enable it to check JS: |
| 139 | + |
| 140 | +```json |
| 141 | +{ |
| 142 | + "compilerOptions": { |
| 143 | + "allowJs": true, |
| 144 | + "checkJs": true |
| 145 | + } |
| 146 | +} |
| 147 | +``` |
| 148 | + |
| 149 | +If you have a large codebase and this throws too many errors at once, you can opt out problematic files with `//@ts-nocheck`, or instead turn off `checkJs` and add a `//@ts-check` directive at the top of each regular JS file. |
| 150 | + |
| 151 | +TypeScript should throw up some egregious errors here which should be easy to fix. |
| 152 | + |
| 153 | +Once you are done, swallow the red pill by turning off implicit `any`'s: |
| 154 | + |
| 155 | +```js |
| 156 | +{ |
| 157 | + "compilerOptions": { |
| 158 | + "allowJs": true, |
| 159 | + "checkJs": true, |
| 160 | + "noImplicitAny": true // or "strict": true |
| 161 | + } |
| 162 | +} |
| 163 | +``` |
| 164 | + |
| 165 | +This will raise a bunch of type errors and you can start converting files to TS or (optionally) use [JSDoc annotations](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html) in your JS. |
| 166 | + |
| 167 | +A common practice here is using an ambient TODO type alias for `any` so you can keep track of what you need to come back to: |
| 168 | + |
| 169 | +```ts |
| 170 | +type TODO_TYPEME = any; |
| 171 | +export function myFunc(foo: TODO_TYPEME, bar: TODO_TYPEME): number { |
| 172 | + // ... |
| 173 | +} |
| 174 | +``` |
| 175 | + |
| 176 | +Gradually add [more `strict` mode flags](https://www.typescriptlang.org/docs/handbook/compiler-options.html) like `noImplicitThis`, `strictNullChecks`, and so on until you can eventually just run in full strict mode with no js files left: |
| 177 | + |
| 178 | +```js |
| 179 | +{ |
| 180 | + "compilerOptions": { |
| 181 | + "strict": true |
| 182 | + } |
| 183 | +} |
| 184 | +``` |
| 185 | + |
| 186 | +**More resources** |
| 187 | + |
| 188 | +- [Adopting TypeScript at Scale - AirBnB's conversion story and strategy](https://www.youtube.com/watch?v=P-J9Eg7hJwE) |
| 189 | +- [Migrating a `create-react-app`/`react-scripts` app to TypeScript](https://facebook.github.io/create-react-app/docs/adding-typescript) - don't use `react-scripts-ts` |
| 190 | +- [Migrating an EJECTED CRA app to TS](https://spin.atomicobject.com/2018/07/04/migrating-cra-typescript/) |
| 191 | +- [Lyft's JS to TS migration tool](https://github.com/lyft/react-javascript-to-typescript-transform) (includes PropTypes migration) |
| 192 | +- [Hootsuite][hootsuite] |
| 193 | +- [Storybook's migration (PR)](https://github.com/storybooks/storybook/issues/5030) |
| 194 | +- [How we migrated a 200K+ LOC project to TypeScript and survived to tell the story][coherentlabs] - Coherent Labs - using `grunt-ts`, jQuery and Kendo UI |
| 195 | + |
| 196 | +Old content that is possibly out of date |
| 197 | + |
| 198 | +- [Incrementally Migrating JS to TS][clayallsop] (old) |
| 199 | +- [Microsoft's TypeScript React Conversion Guide][mstsreactconversionguide] (old) |
| 200 | + |
| 201 | +## From Flow |
| 202 | + |
| 203 | +- Try flow2ts: `npx flow2ts` - doesn't work 100% but saves some time ([see this and other tips from @braposo](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet/pull/79#issuecomment-458227322) at TravelRepublic) |
| 204 | +- [Incremental Migration to TypeScript on a Flowtype codebase][entria] at Entria |
| 205 | +- [MemSQL's Studio's migration](https://davidgom.es/porting-30k-lines-of-code-from-flow-to-typescript/) - blogpost with many useful tips |
| 206 | +- Retail-UI's Codemod: https://github.com/skbkontur/retail-ui/tree/master/packages/react-ui-codemodes/flow-to-ts |
| 207 | +- Quick-n-dirty [Flow to TS Codemod](https://gist.github.com/skovhus/c57367ce6ecbc3f70bb7c80f25727a11) |
| 208 | +- [Ecobee's brief experience](https://mobile.twitter.com/alanhietala/status/1104450494754377728) |
| 209 | +- [Migrating a 50K SLOC Flow + React Native app to TypeScript](https://blog.usejournal.com/migrating-a-flow-react-native-app-to-typescript-c74c7bceae7d) |
| 210 | + |
| 211 | +## Results |
| 212 | + |
| 213 | +- Number of production deploys doubled for [Hootsuite][hootsuite] |
| 214 | +- Found accidental globals for [Tiny][tiny] |
| 215 | +- Found incorrect function calls for [Tiny][tiny] |
| 216 | +- Found rarely used, buggy code that was untested for [Tiny][tiny] |
| 217 | + |
| 218 | +## Misc migration stories by notable companies and open source |
| 219 | + |
| 220 | +- [Adopting TypeScript at Scale - AirBnB's conversion story and strategy](https://www.youtube.com/watch?v=P-J9Eg7hJwE) |
| 221 | +- [Lyft](https://eng.lyft.com/typescript-at-lyft-64f0702346ea) |
| 222 | +- [Google](http://neugierig.org/software/blog/2018/09/typescript-at-google.html) |
| 223 | +- [Tiny][tiny] - [Talk from ForwardJS here](https://www.slideshare.net/tiny/porting-100k-lines-of-code-to-typescript) |
| 224 | +- [Slack](https://slack.engineering/typescript-at-slack-a81307fa288d) ([podcast](https://softwareengineeringdaily.com/2017/08/11/typescript-at-slack-with-felix-rieseberg/)) |
| 225 | +- [Priceline](https://medium.com/priceline-labs/trying-out-typescript-part-1-15a5267215b9) |
| 226 | +- Dropbox - [Talk at React Loop](https://www.youtube.com/watch?v=veXkJq0Z2Qk) |
| 227 | + |
| 228 | +Open Source |
| 229 | + |
| 230 | +- [Jest's migration (PR)](https://github.com/facebook/jest/pull/7554#issuecomment-454358729) |
| 231 | +- [Expo's migration (issue)](https://github.com/expo/expo/issues/2164) |
| 232 | +- [Google Workbox migration](https://github.com/GoogleChrome/workbox/pull/2058) |
| 233 | +- [Atlassian's migration (PR)](https://github.com/atlassian/react-beautiful-dnd/issues/982) |
| 234 | +- [Yarn's migration (issue)](https://github.com/yarnpkg/yarn/issues/6953) |
| 235 | +- [React Native CLI](https://github.com/react-native-community/cli/issues/683) |
| 236 | +- [Next.js](https://nextjs.org/blog/next-9) |
| 237 | +- [Redux](https://github.com/reduxjs/redux/pull/3536) |
| 238 | + |
| 239 | +## Links |
| 240 | + |
| 241 | +[hootsuite]: https://medium.com/hootsuite-engineering/thoughts-on-migrating-to-typescript-5e1a04288202 "Thoughts on migrating to TypeScript" |
| 242 | +[clayallsop]: https://medium.com/@clayallsopp/incrementally-migrating-javascript-to-typescript-565020e49c88 "Incrementally Migrating JavaScript to TypeScript" |
| 243 | +[pleo]: https://medium.com/pleo/migrating-a-babel-project-to-typescript-af6cd0b451f4 "Migrating a Babel project to TypeScript" |
| 244 | +[mstsreactconversionguide]: https://github.com/Microsoft/TypeScript-React-Conversion-Guide "TypeScript React Conversion Guide" |
| 245 | +[entria]: https://medium.com/entria/incremental-migration-to-typescript-on-a-flowtype-codebase-515f6490d92d "Incremental Migration to TypeScript on a Flowtype codebase" |
| 246 | +[coherentlabs]: https://hashnode.com/post/how-we-migrated-a-200k-loc-project-to-typescript-and-survived-to-tell-the-story-ciyzhikcc0001y253w00n11yb "How we migrated a 200K+ LOC project to TypeScript and survived to tell the story" |
| 247 | +[tiny]: https://go.tiny.cloud/blog/benefits-of-gradual-strong-typing-in-javascript/ "Benefits of gradual strong typing in JavaScript" |
0 commit comments