Migrating a Large Flow Monorepo to TypeScript

Summary

Yelp migrated a 1.4-million-line JavaScript monorepo from Flow to TypeScript after community support and package ecosystem tooling shifted toward TypeScript. To maintain continuous type safety without code freezes, engineers converted the codebase package by package starting at the deepest internal dependencies. The toolchain used flowts for code conversion and flowgen to turn generated TypeScript declaration files back into Flow-compatible headers for downstream consumers. Webcore dogfooded the tooling across 90 packages, automated tracking through internal metrics, and assisted feature teams with bottleneck conversions. Completed in February 2026, the migration increased overall type coverage from 83.15% to 96.44% and unlocked TypeScript-only tooling.

Context

Yelp chose Flow in 2017, but by 2021 the broader JavaScript ecosystem favored TypeScript due to larger type definitions on DefinitelyTyped, built-in package headers, and Flow refocusing on internal needs. A single massive rewrite of over 1 million lines of code was unfeasible, requiring a gradual migration that preserved strict type integrity across mixed Flow and TypeScript code in production.

Approach / What changed

Yelp executed a package-by-package migration in a Lerna monorepo, starting from the deepest internal dependencies. They used flowts and custom codemods for conversion, and flowgen to convert TypeScript declaration files into Flow-compatible headers for untranslated consumers. The Webcore team dogfooded the tooling on 90 foundational packages, built an automated tracking pipeline via Jira and Graphviz dependency maps, and manually finished bottleneck packages near the deadline using auto-suppression directives.

Takeaways

• Converting packages from the deepest internal dependencies upward allowed flowgen to supply Flow-compatible headers to dependent code without losing cross-package type integrity.
• Pre-converting 90 foundational styleguide packages during an extensive dogfooding period eliminated blocking dependencies for feature teams before general rollout.
• The migration improved type coverage from 83.15% in Flow to 96.44% across 1.4 million lines of code, leaving roughly 6,000 @ts-expect-error annotations in total.

Related reading