Migrar TypeScript: 7 passos em projeto JavaScript existente

Migrar TypeScript em um projeto JavaScript existente não exige reescrever tudo de uma vez. O compilador foi desenhado para aceitar JavaScript puro, o que permite uma transição gradual, arquivo por arquivo, sem interromper o fluxo de entregas. O resultado esperado ao final do processo: código com tipos verificados, menos bugs de runtime e uma base mais fácil de manter. Antes de começar, garanta que o projeto tem testes automatizados básicos e que o time está confortável com o conceito de tipos estáticos.

Passo 1: Instale o TypeScript como dependência de desenvolvimento

O primeiro passo é adicionar o TypeScript ao projeto. No terminal, execute:

npm install --save-dev typescript

Isso instala o compilador localmente, evitando conflitos de versão entre máquinas. Depois, verifique a instalação com npx tsc --version. Um erro comum aqui é instalar o TypeScript globalmente e esquecer de registrar no package.json, o que quebra a build em outros ambientes.

Dica: adicione um script no package.json para rodar a checagem de tipos: "typecheck": "tsc --noEmit". Isso facilita a integração contínua.

Passo 2: Crie o arquivo tsconfig.json com allowJs

O tsconfig.json é o coração da migração. Crie o arquivo na raiz do projeto com as opções mínimas:

{ "compilerOptions": { "allowJs": true, "checkJs": false, "outDir": "./dist", "target": "es2020", "module": "commonjs", "strict": false }, "include": ["src"] }

A opção allowJs diz ao TypeScript para aceitar arquivos .js no projeto. Com checkJs: false, o compilador não verifica tipos nesses arquivos ainda, o que reduz o ruído inicial. O erro comum é ativar strict: true logo de cara, gerando centenas de erros e desmotivando o time.

Dica: mantenha strict desligado nas primeiras semanas e ligue gradualmente por módulo.

Passo 3: Renomeie arquivos estratégicos de .js para .ts

Comece pelos arquivos com menor dependência, como utilitários, constantes e helpers. Renomeie um arquivo por vez para .ts e rode npx tsc --noEmit para ver o que quebra. O erro comum é tentar converter tudo de uma vez, o que transforma a migração em um projeto paralelo.

Por exemplo, um arquivo utils/format.js vira utils/format.ts. O TypeScript vai reclamar de parâmetros implícitos do tipo any, mas com strict desligado, ele aceita e você pode ajustar depois.

Dica: use a flag --allowJs no comando de compilação para garantir que os arquivos .js restantes continuem funcionando.

Passo 4: Adicione tipos básicos nos arquivos convertidos

Com os arquivos renomeados, comece a anotar tipos simples: parâmetros de função, retornos e variáveis. No lugar de deixar any, use tipos primitivos (string, number, boolean) e interfaces para objetos. Um erro comum é criar tipos genéricos demais no início, o que dificulta a leitura.

Exemplo prático:

function formatDate(date: Date, format: string): string { // ... }

Dica: use o TypeScript Playground ou a documentação oficial para consultar tipos comuns, mas evite copiar tipos complexos sem entender o contexto.

Passo 5: Ative checkJs para arquivos .js restantes

Depois de converter uma parte significativa, ative checkJs: true no tsconfig.json. Isso faz o TypeScript verificar tipos também nos arquivos .js, mas de forma não intrusiva. O erro comum aqui é ignorar os avisos e deixar o checkJs ligado sem resolver nada, o que gera uma falsa sensação de segurança.

Nessa fase, o compilador vai apontar erros em arquivos que você ainda não converteu. Trate-os como prioridade baixa, mas registre em um backlog.

Dica: use comentários // @ts-check em arquivos .js específicos para testar a verificação sem ativar globalmente.

Passo 6: Ajuste as importações e exportações

Ao converter arquivos, as importações de módulos .js podem precisar de ajuste. O TypeScript resolve extensões automaticamente, mas em projetos com CommonJS, às vezes é necessário adicionar esModuleInterop: true no tsconfig.json. Erro comum: esquecer essa opção e ver erros de import com módulos que usam module.exports.

Outro ponto: se o projeto usa paths customizados (como @/utils), configure baseUrl e paths no tsconfig.json para evitar quebra de resolução.

Dica: rode npx tsc --noEmit após cada lote de conversões para detectar erros cedo.

Passo 7: Ative o modo strict e padronize o código

Com a maioria dos arquivos em .ts e os erros resolvidos, ligue strict: true. Esse modo ativa checagens mais rígidas, como noImplicitAny e strictNullChecks. O erro comum é ativar strict sem antes revisar os any explícitos, o que gera uma avalanche de erros.

Resolva os erros em lotes, começando pelos arquivos com mais ocorrências. Depois, padronize o estilo com ESLint + @typescript-eslint, e configure o typecheck no script de CI.

Dica: use npx tsc --noEmit como gate de pull request para impedir que código sem tipos entre na branch principal.

Checklist do que foi feito

Ao concluir os 7 passos, você deve ter:

• TypeScript instalado como dependência de desenvolvimento.
• tsconfig.json com allowJs e checkJs configurados.
• Arquivos estratégicos renomeados para .ts.
• Tipos básicos adicionados nos arquivos convertidos.
• checkJs ativado para arquivos .js restantes.
• Importações e exportações ajustadas.
• Modo strict ativado e erros zerados.

Perguntas frequentes sobre migrar TypeScript

Quanto tempo leva para migrar TypeScript em um projeto grande?

Não há um número fixo. Projetos pequenos podem levar dias, enquanto bases grandes levam semanas ou meses. O tempo depende da quantidade de arquivos, da cobertura de testes e da familiaridade do time com tipos. O processo incremental permite que o desenvolvimento continue normalmente durante a migração.

Posso migrar TypeScript sem parar o desenvolvimento de novas features?

Sim, essa é a principal vantagem da abordagem incremental. Como o TypeScript aceita JavaScript com allowJs, você converte arquivos aos poucos. Novas features podem ser escritas em .ts com tipos desde o início, enquanto o código antigo é convertido conforme a demanda.

O que fazer com bibliotecas que não têm tipos?

Muitas bibliotecas populares já incluem tipos. Para as que não têm, use @types/ quando disponível ou crie um arquivo de declaração próprio com declare module. Em último caso, use any temporariamente, mas documente a pendência para resolver depois.

TypeScript funciona com qualquer framework JavaScript?

Sim, TypeScript é um superset do JavaScript e funciona com React, Vue, Angular, Node.js e outros. O processo de migração é semelhante, mas cada framework tem particularidades. Por exemplo, no React, os componentes exigem tipos para props e estado, enquanto no Node.js, os tipos de módulos nativos precisam de @types/node.

É possível reverter a migração se algo der errado?

Sim, como a migração é incremental e cada arquivo é convertido separadamente, você pode reverter um arquivo específico mudando a extensão de volta para .js. O tsconfig.json pode ser ajustado para desativar checkJs ou strict a qualquer momento. O risco de quebra é baixo se os testes estiverem rodando.

Preciso usar strict mode desde o início?

Não. O strict mode é recomendado para projetos novos, mas em migrações, ele pode gerar frustração. Comece sem strict e ative depois, quando o time já estiver confortável. O importante é chegar lá, não começar lá.