Error JSX en TypeScript: la bandera --jsx y cómo solucionarlo

«Cannot use JSX unless the '--jsx' flag is provided» — ¿qué es esto?

Imagine: está escribiendo con entusiasmo su primera aplicación React en TypeScript. El código se ve perfecto, los componentes están bien pensados, el ánimo es combativo. Ejecuta la compilación — y de repente ve este mensaje frío y aterrador:

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

¿Le suena familiar? No se preocupe, no está solo. Este error es una de las preguntas más populares en Stack Overflow con miles de visitas. Pero, como cualquier acertijo, tiene una solución simple y elegante. En este artículo no solo solucionaremos el error, sino que también entenderemos por qué ocurre y cómo configurar TypeScript para trabajar con JSX de una vez por todas.

Por cierto, si recién comienza su camino en el mundo de TypeScript y React, le recomiendo también revisar nuestros materiales sobre fundamentos de TypeScript — esto le ayudará a evitar muchas trampas al inicio.

¿Por qué TypeScript se queja del JSX?

Analicemos la naturaleza de este error. TypeScript es un lenguaje estricto que no entiende la sintaxis similar a HTML de JSX por defecto. Cuando escribe:

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

TypeScript no ve código familiar, sino algo extraño. Para explicarle al compilador que esos corchetes angulares no son un error, sino parte de su componente React, debe indicar explícitamente la bandera --jsx. Es como darle un traductor a TypeScript: «Oye, estas construcciones son JSX válido, no las toques, procésalas correctamente».

El error ocurre en tres casos típicos:

\n
• Proyecto nuevo — olvidó configurar tsconfig.json para trabajar con React;
\n
• Migración desde JavaScript — está traduciendo el proyecto a TypeScript, pero no actualizó la configuración;
\n
• Uso de archivos .tsx — creó un archivo con extensión .tsx, pero el compilador no sabe qué hacer con él.
\n

La buena noticia: la corrección toma menos de un minuto. La mala noticia: si no sabe dónde buscar, puede perder horas. Solucionemos esto de una vez por todas.

Solución paso a paso: configuración de tsconfig.json

La forma más correcta y recomendada es agregar la configuración JSX en su tsconfig.json. Este archivo es el cerebro de su proyecto TypeScript. Aquí le diremos al compilador cómo procesar JSX.

Paso 1: Abra tsconfig.json

Busque el archivo tsconfig.json en la raíz de su proyecto. Si no existe, créelo. Puede hacerlo con el comando:

npx tsc --init

Este comando generará un archivo de configuración básico con muchas opciones comentadas. No se asuste — solo cambiaremos una línea.

Paso 2: Agregue la opción jsx

Dentro del objeto compilerOptions, agregue (o descomente) la línea:

{\n  "compilerOptions": {\n    "jsx": "react-jsx",\n    // otras configuraciones...\n  }\n}

Tenga en cuenta: el valor "react-jsx" es el estándar moderno para React 17+ y React 18. Si usa una versión antigua de React (anterior a la 17), puede especificar "react". Pero recomiendo encarecidamente "react-jsx" — produce código más optimizado y no requiere importar React en cada archivo.

Paso 3: Guarde y reinicie la compilación

Después de guardar los cambios, el error debería desaparecer. Ejecute la compilación nuevamente:

npm run build\n# o\nnpx tsc

Si hizo todo correctamente, el compilador dejará de quejarse y su aplicación se iniciará.

Formas alternativas: para usuarios avanzados

A veces es necesario verificar rápidamente una hipótesis o ejecutar un script de un solo archivo. En estos casos, puede usar la bandera de línea de comandos:

npx tsc --jsx react-jsx app.tsx

Esta es una solución temporal — no cambia la configuración global del proyecto.