|
| 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 | +- `@ts-ignore` on compiler errors for libraries with no typedefs |
| 10 | +- pick ESLint over TSLint ([source](https://eslint.org/blog/2019/01/future-typescript-eslint)) |
| 11 | +- 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]) |
| 12 | +- consider using `allowJS`? (Source: [clayallsop][clayallsop], [pleo][pleo]) |
| 13 | +- consider `"noImplicitAny": false` if you need a gentler onboarding |
| 14 | +- use `declare` keyword for ambient declarations |
| 15 | + |
| 16 | +<details> |
| 17 | +<summary> |
| 18 | +<b> |
| 19 | +Webpack tips |
| 20 | +</b> |
| 21 | +</summary> |
| 22 | + |
| 23 | +- webpack loader: `awesome-typescript-loader` vs `ts-loader`? (there is some disagreement in community about this) |
| 24 | +- Webpack config: |
| 25 | + |
| 26 | +``` |
| 27 | +module.exports = { |
| 28 | +
|
| 29 | +resolve: { |
| 30 | +- extensions: ['.js', '.jsx'] |
| 31 | ++ extensions: ['.ts', '.tsx', '.js', '.jsx'] |
| 32 | +}, |
| 33 | +
|
| 34 | +// Source maps support ('inline-source-map' also works) |
| 35 | +devtool: 'source-map', |
| 36 | +
|
| 37 | +// Add the loader for .ts files. |
| 38 | +module: { |
| 39 | + loaders: [{ |
| 40 | +- test: /\.jsx?$/, |
| 41 | +- loader: 'babel-loader', |
| 42 | +- exclude: [/node_modules/], |
| 43 | ++ test: /\.(t|j)sx?$/, |
| 44 | ++ loader: ['awesome-typescript-loader?module=es6'], |
| 45 | ++ exclude: [/node_modules/] |
| 46 | ++ }, { |
| 47 | ++ test: /\.js$/, |
| 48 | ++ loader: 'source-map-loader', |
| 49 | ++ enforce: 'pre' |
| 50 | + }] |
| 51 | +} |
| 52 | +}; |
| 53 | +``` |
| 54 | + |
| 55 | +</details> |
| 56 | + |
| 57 | +## JSDoc (Not using TS) |
| 58 | + |
| 59 | +- https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript |
| 60 | +- webpack's codebase uses JSDoc with linting by TS https://twitter.com/TheLarkInn/status/984479953927327744 (some crazy hack: https://twitter.com/thelarkinn/status/996475530944823296) |
| 61 | +- |
| 62 | + |
| 63 | +## From JS |
| 64 | + |
| 65 | +- [TypeScript's official Guide for migrating from JS](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) |
| 66 | +- [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` |
| 67 | +- [Migrating an EJECTED CRA app to TS](https://spin.atomicobject.com/2018/07/04/migrating-cra-typescript/) |
| 68 | +- [Hootsuite][hootsuite] |
| 69 | +- [Storybook's migration (PR)](https://github.com/storybooks/storybook/issues/5030) |
| 70 | +- [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 |
| 71 | + |
| 72 | +Old content that is possibly out of date |
| 73 | + |
| 74 | +- [Incrementally Migrating JS to TS][clayallsop] (old) |
| 75 | +- [Microsoft's TypeScript React Conversion Guide][mstsreactconversionguide] (old) |
| 76 | + |
| 77 | +## From Flow |
| 78 | + |
| 79 | +- [Incremental Migration to TypeScript on a Flowtype codebase][entria] at Entria |
| 80 | +- [Jest's migration (PR)](https://github.com/facebook/jest/pull/7554#issuecomment-454358729) |
| 81 | +- [Expo's migration (issue)](https://github.com/expo/expo/issues/2164) |
| 82 | +- [Atlassian's migration (PR)](https://github.com/atlassian/react-beautiful-dnd/issues/982) |
| 83 | +- [Yarn's migration (issue)](https://github.com/yarnpkg/yarn/issues/6953) |
| 84 | + |
| 85 | +## Results |
| 86 | + |
| 87 | +- Number of production deploys doubled for [Hootsuite][hootsuite] |
| 88 | + |
| 89 | +## Misc writeups by notable companies |
| 90 | + |
| 91 | +- [Lyft](https://eng.lyft.com/typescript-at-lyft-64f0702346ea) |
| 92 | +- [Google](http://neugierig.org/software/blog/2018/09/typescript-at-google.html) |
| 93 | + |
| 94 | +## Links |
| 95 | + |
| 96 | +[hootsuite]: https://medium.com/hootsuite-engineering/thoughts-on-migrating-to-typescript-5e1a04288202 'Thoughts on migrating to TypeScript' |
| 97 | +[clayallsop]: https://medium.com/@clayallsopp/incrementally-migrating-javascript-to-typescript-565020e49c88 'Incrementally Migrating JavaScript to TypeScript' |
| 98 | +[pleo]: https://medium.com/pleo/migrating-a-babel-project-to-typescript-af6cd0b451f4 'Migrating a Babel project to TypeScript' |
| 99 | +[mstsreactconversionguide]: https://github.com/Microsoft/TypeScript-React-Conversion-Guide 'TypeScript React Conversion Guide' |
| 100 | +[entria]: https://medium.com/entria/incremental-migration-to-typescript-on-a-flowtype-codebase-515f6490d92d 'Incremental Migration to TypeScript on a Flowtype codebase' |
| 101 | +[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' |
0 commit comments