Entendendo @ts-ignore e Quando Você Deve Usá-lo

O sistema de tipos do TypeScript detecta erros antes que eles cheguem à produção, mas às vezes você precisa dizer ao compilador para ignorar algo. É aí que entra o @ts-ignore—uma diretiva do TypeScript que suprime erros do compilador para a próxima linha de código. Embora possa ser uma salvação em situações específicas, usá-lo de forma descuidada compromete a própria segurança de tipos que o TypeScript oferece.

Este artigo explica o que o @ts-ignore faz, como ele difere da alternativa mais segura @ts-expect-error, e quando (se é que alguma vez) você deve recorrer a essas diretivas do TypeScript no seu código.

O Que @ts-ignore Faz no TypeScript

A diretiva @ts-ignore é um comentário que instrui o compilador do TypeScript a pular a verificação de tipos para a linha seguinte:

// @ts-ignore
const result: number = "this is actually a string"

Sem a diretiva, o TypeScript lançaria um erro de compilação porque você está atribuindo uma string a uma variável tipada como number. Com @ts-ignore, o erro desaparece—permanente e silenciosamente.

Este comportamento torna o @ts-ignore particularmente perigoso. Uma vez adicionado, ele não fornece feedback se o problema subjacente for corrigido. A diretiva permanece no seu código, potencialmente ocultando novos erros do compilador TypeScript que surgem de mudanças futuras.

@ts-ignore vs @ts-expect-error: Uma Diferença Crítica

O TypeScript 3.9 introduziu o @ts-expect-error, uma alternativa mais segura ao @ts-ignore. A diferença principal? O @ts-expect-error falha a build se não existir erro na próxima linha:

// Usando @ts-ignore (arriscado)
// @ts-ignore
const value: string = getUserName() // Silencioso mesmo após corrigir getUserName()

// Usando @ts-expect-error (mais seguro)
// @ts-expect-error
const value: string = getUserName() // Lança "Unused '@ts-expect-error' directive" quando corrigido

Este comportamento autodocumentado torna o @ts-expect-error superior para as melhores práticas do TypeScript. Ele força você a remover a diretiva assim que o problema subjacente for resolvido, mantendo a segurança de tipos em todo o seu código.

Quando @ts-ignore Pode Ser Aceitável

Apesar dos riscos, existem cenários raros onde o @ts-ignore serve a um propósito legítimo:

Trabalhando com Código Legado

Ao migrar JavaScript para TypeScript, você pode encontrar padrões legados complexos que são difíceis de tipar corretamente:

// @ts-ignore - Lógica de validação legada, refatoração planejada para Q2
return legacyValidator.validateWithCustomRules(data, rules)

Bibliotecas de Terceiros Sem Tipos

Alguns pacotes npm carecem de definições TypeScript, e criar tipos abrangentes nem sempre é viável:

// @ts-ignore - Nenhum pacote @types disponível para ancient-library@1.0.0
import { processData } from 'ancient-library'

Correções Temporárias de Migração

Durante refatorações em larga escala, você pode precisar entregar código funcional antes de completar as atualizações de tipo:

// @ts-ignore - Temporário: Remover após completar migração do tipo User (JIRA-1234)
const user = getOldUserFormat()

Os Custos Ocultos de Usar @ts-ignore em Excesso

Cada @ts-ignore no seu código é dívida técnica. Veja o que você arrisca:

// ❌ Ruim: Ocultando um bug real
// @ts-ignore
const total = calculatePrice(items, "invalid-discount-type")

// ✅ Melhor: Corrija o problema real
const total = calculatePrice(items, DiscountType.PERCENTAGE)

Suprimir erros do compilador TypeScript significa:

• Bugs em tempo de execução que o TypeScript teria detectado
• Refatoração mais difícil à medida que os tipos se tornam não confiáveis
• Suporte reduzido de autocompletar e IntelliSense na IDE
• Confusão para membros da equipe que não podem confiar nos tipos

Aplicando Melhores Práticas com ESLint

O plugin TypeScript ESLint fornece regras para gerenciar o uso de diretivas:

{
  "rules": {
    "@typescript-eslint/prefer-ts-expect-error": "error",
    "@typescript-eslint/ban-ts-comment": [
      "error",
      {
        "ts-ignore": "allow-with-description",
        "minimumDescriptionLength": 10
      }
    ]
  }
}

Esta configuração requer comentários explicativos e encoraja o uso de @ts-expect-error em vez de @ts-ignore, tornando as diretivas TypeScript mais intencionais e rastreáveis.

Melhores Alternativas a Considerar Primeiro

Antes de recorrer ao @ts-ignore, experimente estas abordagens:

// Opção 1: Type assertions (quando você sabe mais que o TypeScript)
const element = document.getElementById('my-id') as HTMLInputElement

// Opção 2: Type guards
if (typeof value === 'string') {
  // TypeScript agora sabe que value é uma string
  console.log(value.toUpperCase())
}

// Opção 3: Definições de tipo adequadas
declare module 'untyped-library' {
  export function someFunction(input: string): number
}

Conclusão

A diretiva @ts-ignore é a saída de emergência do TypeScript—use-a apenas quando nenhuma outra opção existir. Em quase todos os casos, @ts-expect-error fornece uma alternativa mais segura que mantém a responsabilidade no seu código. Melhor ainda, invista tempo em tipagem adequada, type assertions ou type guards para preservar a segurança de tipos que torna o TypeScript valioso.

Lembre-se: cada erro suprimido é um bug potencial esperando para acontecer. Mantenha os erros do compilador TypeScript visíveis, seus tipos honestos e o uso de @ts-ignore em zero absoluto sempre que possível.

Perguntas Frequentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.