Yelp migra monorepo gigante de Flow para TypeScript em 3 anos
Motivação para a migração
Em 2017, a equipe Webcore escolheu Flow como typechecker de JavaScript da Yelp, pois na época oferecia melhor suporte a React, desempenho e um repositório de tipos para pacotes NPM. Com o tempo, o cenário mudou: TypeScript passou a ter mais pacotes tipados, maior adoção na comunidade, mais ferramentas e documentação mais ampla. Em 2021, quando a equipe do Flow anunciou foco nas necessidades internas do Facebook em vez da comunidade open source, a empresa decidiu planejar a transição no início de 2022.
Estratégia gradual
A meta central foi preservar a confiança na checagem de tipos, evitando desativar o typechecker temporariamente ou inserir comentários de ignorância em massa. Uma reescrita completa foi descartada pela dimensão do monorepo, assim como um congelamento de código para migração manual. A saída foi migrar gradualmente, convivendo com Flow e TypeScript ao mesmo tempo no mesmo repositório, sem perder segurança de tipos.
Como a migração foi feita
A conversão foi executada pacote por pacote. A Yelp usou inicialmente a ferramenta aberta flowts e depois adotou o codemod da Stripe para reduzir o trabalho manual. Para permitir interoperabilidade, os arquivos .d.ts gerados pelo TypeScript eram convertidos de volta para cabeçalhos compatíveis com Flow usando a ferramenta flowgen. Como não havia ferramenta equivalente no sentido inverso, a migração precisou começar pelas dependências internas mais profundas e subir pela árvore de dependências.
A existência de um monorepo com Lerna facilitou o processo: permitiu atualizar ferramentas para todo o ecossistema com poucos PRs e lidar com interoperabilidade no nível de pacote, não de arquivo. A maior parte dos pacotes tinha menos de alguns milhares de linhas e podia ser convertida em um ou dois dias.
Preparação e lançamento
Antes de abrir o processo para todos os times, a equipe passou meses em dogfooding, convertendo cerca de 90 pacotes fundamentais, corrigindo problemas na cadeia de ferramentas e escrevendo documentação detalhada. O lançamento geral para times de produto ocorreu em maio de 2023, com apresentações, demonstrações e integração automática de tickets no Jira para indicar pacotes prontos para migração.
Ritmo e desafios
A adoção inicial foi rápida, subindo de cerca de 100 pacotes convertidos para mais de 270 em seis meses, mas o total era de 570 pacotes. O progresso depois desacelerou, já que os times priorizavam features e prazos. Para avançar, a equipe criou métricas de prioridade baseadas no grafo de dependências e visualizações para identificar pacotes cuja conversão desbloquearia mais trabalho.
Ferramentas automáticas e LLMs foram testados, mas não conseguiram converter pacotes inteiros sem intervenção humana de forma confiável. A equipe manteve automação para conversão básica, mas dependeu de esforço manual para erros causados por diferenças entre Flow e TypeScript.
Conclusão e resultados
No final de 2024, com massa crítica de pacotes em TypeScript, a Yelp coordenou os últimos 200 pacotes usando listas trimestrais e prazos planejados. O prazo final foi estendido para o fim de 2025, e a Webcore assumiu manualmente alguns pacotes finais, aceitando supressões pontuais para encerrar o projeto. O último pacote Flow foi migrado em fevereiro de 2026.
Ao todo, foram migradas 1,4 milhão de linhas de código ao longo de três anos e sete meses. O código final ficou com cerca de 6.000 diretivas @ts-expect-error, das quais aproximadamente 2.000 vieram da supressão automática dos últimos pacotes. A cobertura de tipos subiu de 83,15% no Flow para 96,44% no TypeScript.
Entre os resultados, 82% dos engenheiros entrevistados relataram algum aumento de produtividade com TypeScript, e 45% disseram que o ganho foi significativo. A mudança também permitiu adotar ferramentas que não suportavam Flow, como swc, usar recursos exclusivos de TypeScript e obter melhor suporte de LLMs devido ao maior volume de código TypeScript disponível publicamente.