TypeScript para quem já sabe JavaScript: migração passo a passo

TypeScript é JavaScript com tipos estáticos opcionais — e transformou-se no padrão de facto para desenvolvimento JavaScript profissional. Mais de 80% dos projetos Node.js em grandes empresas usam TypeScript. O ecossistema React e todos os principais frameworks frontend adotaram TypeScript como padrão. A razão é simples: tipos estáticos capturam erros em tempo de desenvolvimento que em JavaScript só aparecem em produção — com usuário real recebendo a mensagem de erro.

Por que TypeScript vale o esforço?

JavaScript permite que você passe uma string onde esperava um número, acesse uma propriedade que não existe em um objeto, e chame uma função com os argumentos errados — e só descobre quando o código executa. TypeScript detecta esses erros antes do código rodar, no próprio editor, com sublinhados vermelhos e mensagens descritivas. Para projetos maiores com múltiplos desenvolvedores, a tipagem também serve como documentação viva — a assinatura de uma função TypeScript diz exatamente o que recebe e o que retorna, sem precisar ler a implementação.

Instalação e configuração

npm install -D typescript ts-node @types/node
npx tsc --init  # Gera o tsconfig.json com configurações padrão

O tsconfig.json configurações essenciais para começar:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "strict": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

"strict": true ativa todas as verificações rigorosas — recomendado para projetos novos. Em projetos existentes migrando de JavaScript, pode ser mais prático começar com false e ativar gradualmente.

Tipos básicos: o que muda do JavaScript

// JavaScript
let nome = "Ana"
let idade = 25
let ativo = true

// TypeScript — anotações de tipo
let nome: string = "Ana"
let idade: number = 25
let ativo: boolean = true

// TypeScript inferência automática (melhor prática — não anotar quando óbvio)
let nome = "Ana"     // TypeScript já sabe que é string
let idade = 25       // TypeScript já sabe que é number

// Arrays tipados
const numeros: number[] = [1, 2, 3]
const nomes: string[] = ["Ana", "Carlos", "Maria"]

// Union types: pode ser um tipo OU outro
let id: string | number = "abc123"
id = 42  // OK

// Null e undefined explícitos (com strict: true)
let valor: string | null = null
valor = "texto"  // OK

Interfaces e tipos: defina a forma dos seus objetos

// Interface: define a estrutura de um objeto
interface Usuario {
  id: number
  nome: string
  email: string
  ativo: boolean
  criadoEm?: Date  // ? = opcional
}

// Função tipada
function saudar(usuario: Usuario): string {
  return `Olá, ${usuario.nome}!`
}

// Type: similar à interface, mas mais flexível
type Status = "ativo" | "inativo" | "pendente"  // Union literal

interface Pedido {
  id: number
  status: Status  // Só aceita esses três valores exatos
  valor: number
}

// Generics: tipos parametrizáveis
function primeiroItem(array: T[]): T | undefined {
  return array[0]
}
const primeiroNumero = primeiroItem([1, 2, 3])   // T = number
const primeiraString = primeiroItem(["a", "b"])  // T = string

TypeScript com Express (Node.js)

npm install express
npm install -D @types/express

// src/index.ts
import express, { Request, Response } from 'express'

const app = express()
app.use(express.json())

interface Produto {
  id: number
  nome: string
  preco: number
}

const produtos: Produto[] = []

app.get('/produtos', (req: Request, res: Response) => {
  res.json(produtos)
})

app.post('/produtos', (req: Request, res: Response) => {
  const { nome, preco } = req.body as { nome: string; preco: number }
  const produto: Produto = { id: Date.now(), nome, preco }
  produtos.push(produto)
  res.status(201).json(produto)
})

app.listen(3000)

Estratégia de migração de JS para TS

Não migre tudo de uma vez. A abordagem incremental: renomeie os arquivos de .js para .ts um por um, começando pelos utilitários e funções puras (mais fáceis de tipar). Use any como tipo temporário onde a tipagem é complexa — não é o ideal, mas permite migração gradual. Configure "allowJs": true no tsconfig para que arquivos JS e TS coexistam durante a migração. A maioria dos erros que aparecem durante a migração são bugs reais que TypeScript está revelando — tratar cada um deles é o investimento que previne bugs em produção.