Erro JSX no TypeScript: a flag --jsx e como corrigi-lo

«Cannot use JSX unless the '--jsx' flag is provided» — o que é isso?

Imagine: você está escrevendo com entusiasmo seu primeiro aplicativo React em TypeScript. O código parece perfeito, os componentes estão bem pensados, o ânimo é de batalha. Você inicia a compilação — e de repente vê esta mensagem fria e assustadora:

Cannot use JSX unless the '--jsx' flag is provided.

Familiar? Não se preocupe, você não está sozinho. Este erro é uma das perguntas mais populares no Stack Overflow com milhares de visualizações. Mas, como qualquer enigma, ele tem uma solução simples e elegante. Neste artigo, não vamos apenas corrigir o erro, mas também entender por que ele ocorre e como configurar o TypeScript para trabalhar com JSX de uma vez por todas.

A propósito, se você está apenas começando sua jornada no mundo do TypeScript e React, recomendo também conferir nossos materiais sobre fundamentos do TypeScript — isso ajudará a evitar muitas armadilhas no início.

Por que o TypeScript reclama do JSX?

Vamos entender a natureza deste erro. TypeScript é uma linguagem estrita que não entende a sintaxe HTML-like do JSX por padrão. Quando você escreve:

const element = <h1>Hello, World!</h1>;

O TypeScript não vê código familiar, mas algo estranho. Para explicar ao compilador que esses colchetes angulares não são um erro, mas sim parte do seu componente React, você precisa especificar explicitamente a flag --jsx. É como dar um tradutor ao TypeScript: "Olha, essas construções são JSX válido, não mexa nelas, processe-as corretamente".

O erro ocorre em três casos típicos:

\n
• Novo projeto — você esqueceu de configurar o tsconfig.json para trabalhar com React;
\n
• Migração de JavaScript — você está convertendo o projeto para TypeScript, mas não atualizou a configuração;
\n
• Uso de arquivos .tsx — você criou um arquivo com extensão .tsx, mas o compilador não sabe o que fazer com ele.
\n

A boa notícia: a correção leva menos de um minuto. A má notícia: se você não souber onde procurar, pode perder horas. Vamos corrigir isso de uma vez por todas.

Solução passo a passo: configurando o tsconfig.json

A maneira mais correta e recomendada é adicionar a configuração JSX ao seu tsconfig.json. Este arquivo é o cérebro do seu projeto TypeScript. É aqui que diremos ao compilador como processar JSX.

Passo 1: Abra o tsconfig.json

Encontre o arquivo tsconfig.json na raiz do seu projeto. Se ele não existir, crie-o. Isso pode ser feito com o comando:

npx tsc --init

Este comando gerará um arquivo de configuração básico com muitas opções comentadas. Não se assuste — vamos alterar apenas uma linha.

Passo 2: Adicione a opção jsx

Dentro do objeto compilerOptions, adicione (ou descomente) a linha:

{\n  "compilerOptions": {\n    "jsx": "react-jsx",\n    // outras configurações...\n  }\n}

Observe: o valor "react-jsx" é o padrão moderno para React 17+ e React 18. Se você estiver usando uma versão antiga do React (anterior à 17), pode usar "react". Mas eu recomendo fortemente "react-jsx" — ele produz código mais otimizado e não requer a importação do React em cada arquivo.

Passo 3: Salve e reinicie a compilação

Após salvar as alterações, o erro deve desaparecer. Execute a compilação novamente:

npm run build\n# ou\nnpx tsc

Se você fez tudo corretamente, o compilador parará de reclamar e seu aplicativo será iniciado.

Métodos alternativos: para usuários avançados

Às vezes, é necessário testar rapidamente uma hipótese ou executar um script de arquivo único. Nesses casos, você pode usar a flag de linha de comando:

npx tsc --jsx react-jsx app.tsx

Esta é uma solução temporária — ela não altera as configurações globais do projeto.