Skip to main content

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.


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:

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

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