Migrating (to TypeScript) Cheatsheet
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.
⚠️ This Cheatsheet is extremely new and could use all the help we can get. Solid advice, results, and up to date content all welcome.
Prerequisite
Read TypeScript's official Guide for migrating from JS and you should already be familiar with their React conversion guide.
General Conversion approaches
- Level 0: Don't use TypeScript, use JSDoc
- See our JSDoc section
- Level 1A: Majority JavaScript, increasingly strict TypeScript
- as recommended by official TS guide
- use
allowJS(Experiences: clayallsop, pleo)
- Level 1B: Total rename to TypeScript from the start
- "Just rename all .js files to .ts"?
- use the loosest, bare minimum settings to start with
- Level 2: Strict TypeScript
- use Microsoft's
dts-gento generate.d.tsfiles for your untyped files. This SO answer has more on the topic. - use
declarekeyword for ambient declarations - see declaration merging to patch library declarations inline
- use Microsoft's
Misc tips/approaches successful companies have taken
@ts-expect-erroron compiler errors for libraries with no typedefs- pick ESLint over TSLint (source: ESLint and TS Roadmap). You can convert TSlint to ESlint with this tool.
- 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)
Webpack tips
- webpack loader:
awesome-typescript-loadervsts-loader? (there is some disagreement in community about this - but read awesome's point of view) - Webpack config:
module.exports = {
resolve: {
- extensions: ['.js', '.jsx']
+ extensions: ['.ts', '.tsx', '.js', '.jsx']
},
// Source maps support ('inline-source-map' also works)
devtool: 'source-map',
// Add the loader for .ts files.
module: {
loaders: [{
- test: /\.jsx?$/,
- loader: 'babel-loader',
- exclude: [/node_modules/],
+ test: /\.(t|j)sx?$/,
+ loader: ['awesome-typescript-loader?module=es6'],
+ exclude: [/node_modules/]
+ }, {
+ test: /\.js$/,
+ loader: 'source-map-loader',
+ enforce: 'pre'
}]
}
};
Special note on ts-loader and 3rd party libraries: https://twitter.com/acemarke/status/1091150384184229888
Academic Studies of Migration
Note: Empirical Software Engineering is desirable, but extremely hard. Please be gentle but also please share if you find quality research!
Our central finding is that both static type systems find an important percentage of public bugs: both Flow 0.30 and TypeScript 2.0 successfully detect 15%!
see also Things I was Wrong About: Types and A Large Scale Study of Programming Languages and Code Quality in GitHub
Misc migration stories by notable companies and open source
- (2022) Stripe: https://stripe.com/blog/migrating-to-typescript (podcast, tweet)
- Bloomberg - Podcast form
- Adopting TypeScript at Scale - AirBnB's conversion story and strategy
- Airtable's Big Bang Migration from Flow to TS
- Lyft
- Tiny - Talk from ForwardJS here
- Slack (podcast)
- Etsy
- Netflix adoption story
- Priceline
- Dropbox
- Heap - How we failed, then succeeded, at migrating to TypeScript
- Execute Program (Gary Bernhardt) https://www.executeprogram.com/blog/porting-to-typescript-solved-our-api-woes
Open Source
- Jest's migration (PR)
- Expo's migration (issue)
- Google Workbox migration
- Chrome Dev Tools related issues
- Atlassian's migration (PR)
- Yarn's migration (issue)
- React Native CLI
- Next.js
- React Router
- Docusaurus v2
- Gatsby
- Redux
- Theme-UI
- Hasura Console
- Storybook
- Dojo 1 -> 2 migration