JSX Error in TypeScript: The --jsx Flag and How to Fix It

"Cannot use JSX unless the '--jsx' flag is provided" — What is this beast?

Imagine: you are enthusiastically writing your first React application in TypeScript. The code looks perfect, the components are well thought out, the mood is combative. You start the compilation — and suddenly you see this cold, frightening message:

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

Sound familiar? Don't worry, you are not alone. This error is one of the most popular questions on Stack Overflow with thousands of views. But, like any mystery, it has a simple and elegant solution. In this article, we will not just fix the error, but also understand why it occurs and how to configure TypeScript to work with JSX once and for all.

By the way, if you are just starting your journey into the world of TypeScript and React, I also recommend checking out our materials on TypeScript basics — this will help you avoid many pitfalls at the start.

Why does TypeScript complain about JSX?

Let's understand the nature of this error. TypeScript is a strict language that does not understand HTML-like JSX syntax by default. When you write:

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

TypeScript sees not familiar code, but something foreign. To explain to the compiler that these angle brackets are not an error, but part of your React component, you need to explicitly specify the --jsx flag. It's like giving TypeScript a translator: "Listen, these constructs are valid JSX, don't touch them, but process them correctly."

The error occurs in three typical cases:

\n
• New project — you forgot to configure tsconfig.json for working with React;
\n
• Migration from JavaScript — you are converting a project to TypeScript, but haven't updated the configuration;
\n
• Using .tsx files — you created a file with the .tsx extension, but the compiler doesn't know what to do with it.
\n

The good news: the fix takes less than a minute. The bad news: if you don't know where to look, you can spend hours. Let's fix this once and for all.

Step-by-step solution: configuring tsconfig.json

The most correct and recommended way is to add the JSX setting to your tsconfig.json. This file is the brain of your TypeScript project. This is where we will tell the compiler how to handle JSX.

Step 1: Open tsconfig.json

Find the tsconfig.json file in the root of your project. If it doesn't exist, create it. This can be done with the command:

npx tsc --init

This command will generate a basic configuration file with many commented-out options. Don't be scared — we will only change one line.

Step 2: Add the jsx option

Inside the compilerOptions object, add (or uncomment) the line:

{\n  "compilerOptions": {\n    "jsx": "react-jsx",\n    // other settings...\n  }\n}

Note: the value "react-jsx" is the modern standard for React 17+ and React 18. If you are using an older version of React (before 17), you can specify "react". But I strongly recommend "react-jsx" — it produces more optimized code and does not require importing React in every file.

Step 3: Save and restart the compilation

After saving the changes, the error should disappear. Run the build again:

npm run build\n# or\nnpx tsc

If you did everything correctly, the compiler will stop complaining, and your application will run.

Alternative methods: for advanced users

Sometimes you need to quickly test a hypothesis or run a single-file script. In such cases, you can use the command line flag:

npx tsc --jsx react-jsx app.tsx

This is a temporary solution — it does not change the global project settings.