Erreur JSX dans TypeScript : le flag --jsx et comment la corriger

«Cannot use JSX unless the '--jsx' flag is provided» — qu'est-ce que c'est que cette bête ?

Imaginez : vous écrivez avec enthousiasme votre première application React en TypeScript. Le code est parfait, les composants sont bien pensés, l'ambiance est au beau fixe. Vous lancez la compilation — et soudain, vous voyez ce message froid et effrayant :

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

Ça vous dit quelque chose ? Ne vous inquiétez pas, vous n'êtes pas seul. Cette erreur est l'une des questions les plus populaires sur Stack Overflow avec des milliers de vues. Mais, comme toute énigme, elle a une solution simple et élégante. Dans cet article, nous ne nous contenterons pas de corriger l'erreur, mais nous comprendrons pourquoi elle se produit et comment configurer TypeScript pour travailler avec JSX une fois pour toutes.

D'ailleurs, si vous débutez tout juste votre parcours dans le monde de TypeScript et React, je vous recommande également de consulter nos articles sur les bases de TypeScript — cela vous aidera à éviter de nombreux pièges dès le départ.

Pourquoi TypeScript râle-t-il sur le JSX ?

Décortiquons la nature de cette erreur. TypeScript est un langage strict qui ne comprend pas la syntaxe HTML-like du JSX par défaut. Lorsque vous écrivez :

const element = <h1>Bonjour, le monde !</h1>;

TypeScript ne voit pas un code familier, mais quelque chose d'étranger. Pour expliquer au compilateur que ces chevrons ne sont pas une erreur, mais une partie de votre composant React, vous devez explicitement spécifier le flag --jsx. C'est comme donner un interprète à TypeScript : « Écoute, ces constructions sont du JSX valide, ne les touche pas, traite-les correctement ».

L'erreur se produit dans trois cas typiques :

\n
• Nouveau projet — vous avez oublié de configurer tsconfig.json pour fonctionner avec React ;
\n
• Migration depuis JavaScript — vous traduisez un projet en TypeScript, mais vous n'avez pas mis à jour la configuration ;
\n
• Utilisation de fichiers .tsx — vous avez créé un fichier avec l'extension .tsx, mais le compilateur ne sait pas quoi en faire.
\n

Bonne nouvelle : la correction prend moins d'une minute. Mauvaise nouvelle : si vous ne savez pas où chercher, vous pouvez y passer des heures. Corrigeons cela une fois pour toutes.

Solution étape par étape : configuration de tsconfig.json

La méthode la plus correcte et recommandée est d'ajouter la configuration JSX dans votre tsconfig.json. Ce fichier est le cerveau de votre projet TypeScript. C'est ici que nous dirons au compilateur comment traiter le JSX.

Étape 1 : Ouvrez tsconfig.json

Trouvez le fichier tsconfig.json à la racine de votre projet. S'il n'existe pas, créez-le. Cela peut être fait avec la commande :

npx tsc --init

Cette commande générera un fichier de configuration de base avec de nombreuses options commentées. Ne paniquez pas — nous allons changer une seule ligne.

Étape 2 : Ajoutez l'option jsx

À l'intérieur de l'objet compilerOptions, ajoutez (ou décommentez) la ligne :

{\n  "compilerOptions": {\n    "jsx": "react-jsx",\n    // autres paramètres...\n  }\n}

Notez que la valeur "react-jsx" est le standard moderne pour React 17+ et React 18. Si vous utilisez une ancienne version de React (antérieure à 17), vous pouvez spécifier "react". Mais je recommande vivement "react-jsx" — il produit un code plus optimisé et ne nécessite pas d'importer React dans chaque fichier.

Étape 3 : Sauvegardez et relancez la compilation

Après avoir sauvegardé les modifications, l'erreur devrait disparaître. Relancez la construction :

npm run build\n# ou\nnpx tsc

Si vous avez tout fait correctement, le compilateur cessera de râler et votre application démarrera.

Méthodes alternatives : pour les utilisateurs avancés

Parfois, vous devez rapidement vérifier une hypothèse ou exécuter un script d'un seul fichier. Dans ces cas, vous pouvez utiliser le flag de ligne de commande :

npx tsc --jsx react-jsx app.tsx

C'est une solution temporaire — elle ne modifie pas les paramètres globaux du projet.