|
| 1 | +# Migrating (to TypeScript) Cheatsheet |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +> ⚠️ This Cheatsheet is extremely new and could use all the help we can get. Solid advice, results, and up to date content all welcome. |
| 6 | +
|
| 7 | +## General Conversion approaches |
| 8 | + |
| 9 | +- Level 0: Don't use TypeScript, use JSDoc |
| 10 | + - See our [JSDoc section](#JSDoc) |
| 11 | +- Level 1: Unstrict TypeScript |
| 12 | + - `"noImplicitAny": false` |
| 13 | + - "[Just rename all .js files to .ts](https://twitter.com/jamonholmgren/status/1089241726303199232)" |
| 14 | + - consider using `allowJS`? (Source: [clayallsop][clayallsop], [pleo][pleo]) |
| 15 | +- Level 2: Strict TypeScript |
| 16 | + - 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. |
| 17 | + - use `declare` keyword for ambient declarations |
| 18 | + |
| 19 | + |
| 20 | +Misc tips/approaches successful companies have taken |
| 21 | + |
| 22 | +- `@ts-ignore` on compiler errors for libraries with no typedefs |
| 23 | +- pick ESLint over TSLint ([source](https://eslint.org/blog/2019/01/future-typescript-eslint)) |
| 24 | +- 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]) |
| 25 | + |
| 26 | + |
| 27 | +<details> |
| 28 | +<summary> |
| 29 | +<b> |
| 30 | +Webpack tips |
| 31 | +</b> |
| 32 | +</summary> |
| 33 | + |
| 34 | +- webpack loader: `awesome-typescript-loader` vs `ts-loader`? (there is some disagreement in community about this) |
| 35 | +- Webpack config: |
| 36 | + |
| 37 | +``` |
| 38 | +module.exports = { |
| 39 | +
|
| 40 | +resolve: { |
| 41 | +- extensions: ['.js', '.jsx'] |
| 42 | ++ extensions: ['.ts', '.tsx', '.js', '.jsx'] |
| 43 | +}, |
| 44 | +
|
| 45 | +// Source maps support ('inline-source-map' also works) |
| 46 | +devtool: 'source-map', |
| 47 | +
|
| 48 | +// Add the loader for .ts files. |
| 49 | +module: { |
| 50 | + loaders: [{ |
| 51 | +- test: /\.jsx?$/, |
| 52 | +- loader: 'babel-loader', |
| 53 | +- exclude: [/node_modules/], |
| 54 | ++ test: /\.(t|j)sx?$/, |
| 55 | ++ loader: ['awesome-typescript-loader?module=es6'], |
| 56 | ++ exclude: [/node_modules/] |
| 57 | ++ }, { |
| 58 | ++ test: /\.js$/, |
| 59 | ++ loader: 'source-map-loader', |
| 60 | ++ enforce: 'pre' |
| 61 | + }] |
| 62 | +} |
| 63 | +}; |
| 64 | +``` |
| 65 | + |
| 66 | +</details> |
| 67 | + |
| 68 | +## JSDoc |
| 69 | + |
| 70 | +- https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript |
| 71 | +- webpack's codebase uses JSDoc with linting by TS https://twitter.com/TheLarkInn/status/984479953927327744 (some crazy hack: https://twitter.com/thelarkinn/status/996475530944823296) |
| 72 | + |
| 73 | +Problems to be aware of: |
| 74 | + |
| 75 | +- `object` is converted to `any` for some reason. |
| 76 | +- If you have an error in the jsdoc, you get no warning/error. TS just silently doesn't type annotate the function. |
| 77 | +- [casting can be verbose](https://twitter.com/bahmutov/status/1089229349637754880) |
| 78 | + |
| 79 | +(*thanks [Gil Tayar](https://twitter.com/giltayar/status/1089228919260221441) and [Gleb Bahmutov](https://twitter.com/bahmutov/status/1089229196247908353) for sharing above commentary*) |
| 80 | + |
| 81 | +## From JS |
| 82 | + |
| 83 | +- [TypeScript's official Guide for migrating from JS](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) |
| 84 | +- [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` |
| 85 | +- [Migrating an EJECTED CRA app to TS](https://spin.atomicobject.com/2018/07/04/migrating-cra-typescript/) |
| 86 | +- [Lyft's JS to TS migration tool](https://github.com/lyft/react-javascript-to-typescript-transform) (includes PropTypes migration) |
| 87 | +- [Hootsuite][hootsuite] |
| 88 | +- [Storybook's migration (PR)](https://github.com/storybooks/storybook/issues/5030) |
| 89 | +- [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 |
| 90 | + |
| 91 | +Old content that is possibly out of date |
| 92 | + |
| 93 | +- [Incrementally Migrating JS to TS][clayallsop] (old) |
| 94 | +- [Microsoft's TypeScript React Conversion Guide][mstsreactconversionguide] (old) |
| 95 | + |
| 96 | +## From Flow |
| 97 | + |
| 98 | +- Try flow2ts: `npx flow2ts` - doesn't work 100% but saves some time ([see this and other tips from @braposo](https://github.com/sw-yx/react-typescript-cheatsheet/pull/79#issuecomment-458227322) at TravelRepublic) |
| 99 | +- [Incremental Migration to TypeScript on a Flowtype codebase][entria] at Entria |
| 100 | +- [Jest's migration (PR)](https://github.com/facebook/jest/pull/7554#issuecomment-454358729) |
| 101 | +- [Expo's migration (issue)](https://github.com/expo/expo/issues/2164) |
| 102 | +- [Atlassian's migration (PR)](https://github.com/atlassian/react-beautiful-dnd/issues/982) |
| 103 | +- [Yarn's migration (issue)](https://github.com/yarnpkg/yarn/issues/6953) |
| 104 | +- [MemSQL's Studio's migration](https://davidgom.es/porting-30k-lines-of-code-from-flow-to-typescript/) - blogpost with many useful tips |
| 105 | + |
| 106 | +## Results |
| 107 | + |
| 108 | +- Number of production deploys doubled for [Hootsuite][hootsuite] |
| 109 | +- Found accidental globals for [Tiny][tiny] |
| 110 | +- Found incorrect function calls for [Tiny][tiny] |
| 111 | +- Found rarely used, buggy code that was untested for [Tiny][tiny] |
| 112 | + |
| 113 | +## Misc writeups by notable companies |
| 114 | + |
| 115 | +- [Lyft](https://eng.lyft.com/typescript-at-lyft-64f0702346ea) |
| 116 | +- [Google](http://neugierig.org/software/blog/2018/09/typescript-at-google.html) |
| 117 | +- [Tiny][tiny] - [Talk from ForwardJS here](https://www.slideshare.net/tiny/porting-100k-lines-of-code-to-typescript) |
| 118 | +- [Slack](https://slack.engineering/typescript-at-slack-a81307fa288d) |
| 119 | + |
| 120 | +## Links |
| 121 | + |
| 122 | +[hootsuite]: https://medium.com/hootsuite-engineering/thoughts-on-migrating-to-typescript-5e1a04288202 'Thoughts on migrating to TypeScript' |
| 123 | +[clayallsop]: https://medium.com/@clayallsopp/incrementally-migrating-javascript-to-typescript-565020e49c88 'Incrementally Migrating JavaScript to TypeScript' |
| 124 | +[pleo]: https://medium.com/pleo/migrating-a-babel-project-to-typescript-af6cd0b451f4 'Migrating a Babel project to TypeScript' |
| 125 | +[mstsreactconversionguide]: https://github.com/Microsoft/TypeScript-React-Conversion-Guide 'TypeScript React Conversion Guide' |
| 126 | +[entria]: https://medium.com/entria/incremental-migration-to-typescript-on-a-flowtype-codebase-515f6490d92d 'Incremental Migration to TypeScript on a Flowtype codebase' |
| 127 | +[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' |
| 128 | +[tiny]: https://go.tiny.cloud/blog/benefits-of-gradual-strong-typing-in-javascript/ 'Benefits of gradual strong typing in JavaScript' |
0 commit comments