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
  • Level 1A: Majority JavaScript, increasingly strict TypeScript
  • Level 1B: Total rename to TypeScript from the start
  • Level 2: Strict TypeScript
    • use Microsoft's dts-gen to generate .d.ts files for your untyped files. This SO answer has more on the topic.
    • use declare keyword for ambient declarations - see declaration merging to patch library declarations inline

Misc tips/approaches successful companies have taken

Webpack tips
  • webpack loader: awesome-typescript-loader vs ts-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

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%!

Misc migration stories by notable companies and open source

Open Source

Migration Results

  • Number of production deploys doubled for Hootsuite
  • Found accidental globals for Tiny
  • Found incorrect function calls for Tiny
  • Found rarely used, buggy code that was untested for Tiny