TypeScript em projetos React: o que vale a pena tipar

Tipagem é ferramenta de manutenção, não de correção

TypeScript não impede bugs de lógica. O que ele faz é tornar explícito um contrato que, em JavaScript, existe só na cabeça de quem escreveu.

O retorno aparece no dia em que outra pessoa — ou você seis meses depois — precisa mudar algo. Em projeto que ninguém vai manter, o custo não se paga. Em projeto que vive anos, se paga na primeira refatoração.

Onde tipar sempre

• A fronteira com a rede. Tudo que chega de uma API é unknown até ser validado. Este é o único lugar onde tipo sem validação em runtime é perigoso: o TypeScript acredita no que você declarou, e a API não tem obrigação de cumprir.
• Props de componente. É a documentação que não desatualiza.
• Estado compartilhado. Contexto, store, reducer. Onde o dado passa por muitas mãos, o tipo é o que evita divergência.
• Funções de domínio. Cálculo, regra, transformação. Entrada e saída explícitas.

Onde tipar é burocracia

• Anotar o retorno de uma função que o compilador já infere corretamente.
• Criar uma interface para um objeto usado uma vez, dez linhas abaixo.
• Redefinir tipos que a biblioteca já exporta. Se o SDK exporta MessageParam, use MessageParam.
• Genéricos elaborados para um componente com dois usos.

Tipo que só existe para satisfazer o linter é custo sem retorno.

any e a alternativa honesta

any desliga a verificação e propaga silenciosamente pelo código. unknown desliga o acesso até você provar o que é — é o mesmo reconhecimento de ignorância, mas obriga a tratar.

A regra prática: quando não souber o tipo, use unknown e valide. Se usar any, deixe um comentário dizendo por quê. any sem justificativa é dívida que ninguém lembra de cobrar.

Validação em runtime não é opcional na borda

Tipos desaparecem na compilação. Um interface User não verifica nada em produção.

Na fronteira — resposta de API, parâmetro de URL, dado de formulário, conteúdo de localStorage — é preciso validar de verdade, com Zod, Valibot ou uma função escrita à mão. O tipo derivado da validação passa a valer, porque foi conferido.

Sem isso, TypeScript dá uma sensação de segurança que o runtime não sustenta.

O critério para decidir caso a caso

Antes de escrever um tipo, pergunte: se isso mudar e o tipo não acompanhar, alguém quebra?

Se sim, tipe. Se não, você está escrevendo documentação que vai desatualizar e ninguém vai ler.