We're moving to TypeScript! 🎉

[dimitropoulos]

This umbrella issue will outline the transition of the entire insomnia codebase from Flow (or plain JS) to 1st-class idiomatic TypeScript.

Phases

This work will be conducted in a few phases.

🎣 Phase 0: reconnaissance and spike

Reconnaissance

Many projects before us have undergone this same transition. Here are some examples:

1. Yarn Yarn's Future - v2 and beyond yarnpkg/yarn#6953
2. Jest ☂️TypeScript migration tracking issue jestjs/jest#7807
3. Graphql-js Convert flow types to TS graphql/graphql-js#2828, Road to Typescript graphql/graphql-js#2104
4. Luxon Convert codebase to TypeScript moment/luxon#548
5. Gatsby [Umbrella] TypeScript Migration (Help wanted!) gatsbyjs/gatsby#21995
6. Expo [RFC] First-class support for TypeScript in the Expo SDK expo/expo#2164
7. Styled-Components typescript styled-components/styled-components#3460
8. codemirror-graphql Convert LSP packages to TS (WIP) graphql/graphiql#957

Spike

@develohpanda conducted the initial spike using 22935ec...122785f

Update: we later learned that this missed one little thing: decorators. This spike was done on o2k, which doesn't contain any decorators. More on this later, below.

🔰 Phase 1 - initial packages

Similar to almost all of the conversions listed above, we will be taking this conversion in a "bottom up" approach where we will be converting many of the things without dependencies first. This conversion will aim to be fairly final in nature. Some ambient declarations will be necessary here and there for packages we can't upgrade (which, is a common thing to happen in a conversion like this so that we can have access to types), but in general the hope is do a fairly thorough job such that we won't have a step later to come back and fix a lot of things up.

Phase 1 Checklist

Task	PR	Status
insomnia-xpath	#3267	Done
insomnia-url	#3267	Done
insomnia-prettify	#3267	Done
insomnia-importers	#3267	Done
insomnia-cookies	#3267	Done
insomina-testing	#3267	Done
insomnia-inso	#3267	Done

🦺 Phase 2 - app's rough conversion

We will then be converting the bulk of the codebase (insomnia-app) to TypeScript using a script that uses https://github.com/Khan/flow-to-ts. The goal of this phase is to do the conversion with as much automation as physically possible, taking every opportunity to use @ts-expect-error and other workarounds.

The bulk of the manual work for this phase will come in the form of updates to the build pipeline (e.g. webpack).

We know that this is going to be a noisy time for all open/existing PRs, so we have planned it in this way to lessen the burden. We know from the spike of this phase that we may need to first submit a PR that simply upgrades the codebase to prettier v2 (which is required by flow-to-ts, but is also required by us anyway if we're going to be using prettier because prettier v1 doesn't support the version of TypeScript that we're on).

One benefit of doing things this way is that we'll be able to go and update most PRs (as part of this phase) by simply running the script mentioned above. We will temporarily check the script into the source code while phase 2 is ongoing.

That said, things will probably feel fairly shaky at this step because the codebase will have lots of @ts-expect-errors and other opting-out of the type system.

Phase 2 Checklist

Task	PR	Status
convert everything to prettier 2	#3370	Done
create conversion script	#3370	Done
insomnia-app	#3370	Done
insomnia-components	#3370	Done
insomnia-smoke-test	#3374	Done
openapi-2-kong	#3370	Done

🥅 Phase 3 - Moar and better TypeScript

Since by this phase Flow will be completely gone, we'll be able to scavenge the codebase for any of the @ts-expect-errors and other opting-out of the typesystems that we did and fix them all. By the completion of this phase we will have quite a large portion of the codebase into idiomatic TypeScript.

Another component of this is to enable type-checking (such that a typescript error alone will fail a test suite) in tests by setting isolatedModules: false in our jest configs.

Phase 3 Checklist

Task	PR	Status
insomnia-app
insomnia-components
insomnia-smoke-test
openapi-2-kong
isolatedModules: false

🧹 Phase 4 - plugins and cleanup

That leaves the plugins. Many of the plugins are quite small and from our current estimates it should be quite reasonable to do them all in one step (or, PR).

Once that's complete, the entire codebase with almost no single exception should be in TypeScript. There are a few cleanup tasks I've assembled from the spike work an Phase 1 (this list will be updated as we go along):

• remove vestiges of Flow
  • Make sure all flow-typed directories were removed
  • Remove any eslint disables of flow rules
  • Remove any remaining // @flow
  • Remove comments that contain flow e.g. // make flow happy
  • Remove the typecheck step from the CI
  • Make sure all typecheck scripts are gone from all package.jsons
  • Attempt to clear all usages of utility-types
  • remove any "```flow" or "```js" codefences in markdown files (or elsewhere) and replace with "```ts"
• leverage TypeScript in tooling
  • Make sure all js files that possibly can have types, e.g.: /** @type { import('webpack').Configuration } */ before webpack configs and /** @type {import('@jest/types').Config.InitialOptions} */ before jest configs
  • Search package.jsons for "jest": { to make sure all jest configs are separate (TypeScript checked) .js files and not package.json addons
  • Search codebase for any module.exports and make sure they only exist in config files that (due to their place in the build chain) cannot be transpiled
  • make sure every package has a clean and postclean npm script that removes the typescript built files
  • make sure every package.json has build and lint
  • May of the plain-js packages didn't need a build step during lerna bootstrap but now will. make sure they all have it. (perhaps a test for this is a clean clone followed by yarn and yarn bootstrap)
• TypeScript conversion
  • run npx typesync in every package
  • Make sure all index.ts files are simple exporters without other source code
  • make sure all tsconfig.build.json files exclude tests (including mocks and fixtures)
  • make sure all tsconfig.build.json files extend the base and that the tsconfig.json files extend the build (and not the other way around).
• General Cleanup
  • Search repo for any remaining TODO(TSCONVERSION)
  • remove TypeScript conversion script
  • remove any temp-disabled from package.jsons (used during testing to individually disable errant scripts).

Phase 4 checklist

Task	PR	Status
remove vestiges of Flow
leverage TypeScript tooling
TypeScript conversion
General Cleanup
insomnia-plugin-base64
insomnia-plugin-cookie-jar
insomnia-plugin-core-themes
insomnia-plugin-default-headers
insomnia-plugin-file
insomnia-plugin-hash
insomnia-plugin-jsonpath
insomnia-plugin-kong-bundle
insomnia-plugin-kong-declarative-config
insomnia-plugin-kong-kubernetes-config
insomnia-plugin-kong-portal
insomnia-plugin-now
insomnia-plugin-os
insomnia-plugin-prompt
insomnia-plugin-request
insomnia-plugin-response
insomnia-plugin-uuid