# Migrar TypeScript: 7 passos em projeto JavaScript existente > A migração TypeScript em um projeto JavaScript existente segue um processo incremental de sete etapas, iniciando pela configuração do compilador e análise de tipos. A transição ocorre sem interromper o time, priorizando arquivos críticos e ajustando gradualmente o código. TypeScript oferece compatibilidade com JavaScript, permitindo adoção progressiva e redução de erros em runtime. A estratégia exige versionamento contínuo e testes automatizados para garantir estabilidade durante a conversão. *TNT Web · Apps e Software · 31 de julho de 2026 · Dani Travassos* Migrar TypeScript em um projeto JavaScript existente parece trabalhoso, mas com um plano passo a passo é possível fazer a transição sem parar o time. Veja como começar. 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á. --- Fonte (canonical): https://tntweb.com.br/apps-e-software/migrar-typescript-7-passos-em-projeto-javascript-existente/