How to Fix "Cannot use JSX unless the '--jsx' flag is provided" in TypeScript React

By the end of this page, you will understand what the jsx TypeScript setting does, why this error can still appear even when tsconfig.json looks correct, and how to debug common causes such as the wrong project being loaded, files not being included, editor TypeScript issues, and mismatched React/TypeScript configuration.

TypeScript treats JSX as a special syntax feature. Files such as .tsx contain HTML-like tags inside JavaScript or TypeScript code, so the compiler must be explicitly told how to handle that syntax.

If TypeScript does not see a valid JSX setting, it reports:

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

This usually means one of these things:

• your editor is not using the tsconfig.json you expect
• the .tsx file is outside the include paths
• the file is being treated as part of a different TypeScript project
• the TypeScript server in the editor needs to be restarted
• the compiler configuration is valid, but your toolchain and editor are not reading the same config

A very important point: Babel compiling your code does not automatically control TypeScript's type-checking behavior in your editor. Babel can transform TSX successfully, while TypeScript in the editor still shows errors if its own configuration is wrong or not loaded.

So the real concept here is not just "set jsx to react". It is understanding that:

• Babel transpiles code
• TypeScript checks code and powers editor diagnostics
• both tools may exist in the same project, but they each need correct configuration

In real projects, many JSX errors come from project setup issues rather than syntax mistakes.

Think of your project like a building with multiple security desks.

• Babel is one desk that says: "I know how to transform this code."
• TypeScript is another desk that says: "I know how to analyze this code."
• Your editor is a third desk that asks TypeScript questions in real time.

Even if Babel lets your .tsx file into the building, your editor can still block it if TypeScript was not told that JSX is allowed.

So this error often means: the wrong desk is checking your file, or the right desk does not have the right instructions.

The key TypeScript setting is jsx inside compilerOptions.

Basic syntax

{
  "compilerOptions": {
    "jsx": "react"
  }
}

Common values include:

• react — classic React JSX transform
• react-jsx — newer React 17+ transform
• preserve — keep JSX as-is for another tool like Babel

Example TSX file

import React from 'react';

export function Hello() {
  return <h1>Hello</h1>;
}

If this file is inside your TypeScript project and jsx is configured correctly, TypeScript should understand the JSX syntax.

Consider this project structure:

project/
  tsconfig.json
  lib/
    App.tsx

And this config:

{
  "compilerOptions": {
    "jsx": "react",
    "noEmit": true
  },
  "include": ["lib/**/*"]
}

And this file:

export function App() {
  return <div>Hi</div>;
}

What TypeScript does step by step

1. It loads tsconfig.json.
2. It reads include and finds files under lib/.

JSX configuration matters in many common setups.

React applications

A React app with TypeScript almost always needs .tsx support for component files:

function Button() {
  return <button>Save</button>;
}

Without a proper JSX setting, the editor cannot parse this.

Next.js and frontend frameworks

Frameworks often manage Babel or SWC internally, but TypeScript still needs to understand JSX for type checking and editor support.

Shared component libraries

A design system may contain many .tsx files. If the wrong include path is used, some components may suddenly show JSX errors while others work.

Monorepos

In a monorepo, each package may have its own tsconfig.json. A file may accidentally be opened under the wrong package config, causing this exact error.

Migration from JavaScript to TypeScript

When teams gradually rename files from .js to .tsx, they often forget to update include, , or editor project boundaries.

In real projects, developers usually solve this by treating TypeScript configuration as a project boundary problem.

Common patterns

Keep source files under a clear folder

Example:

src/
components/

Then use:

"include": ["src/**/*"]

This reduces confusion about which files belong to the project.

Use noEmit when Babel handles output

If Babel builds the app, TypeScript can focus on type checking only:

{
  "compilerOptions": {
    "noEmit": true,
    "jsx": "preserve"
  }
}

Use guard-rail scripts in package.json

Here are the most common mistakes behind this error.

1. The file is not included in the project

Broken config:

{
  "include": ["lib/**/*"]
}

But file location:

src/App.tsx

Fix

Include the correct folder:

{
  "include": ["src/**/*", "lib/**/*"]
}

2. Using .ts instead of .tsx

Broken:

App.ts

export function App() {
  return ;
}

{
  "compilerOptions": {
    "jsx": "preserve"
  }
}

Quick rules

• JSX in TypeScript requires .tsx files
• TypeScript must see a valid jsx option
• The file must be inside the project's include paths
• Babel config does not replace TypeScript config
• Editor errors may come from the wrong TypeScript project being loaded

Useful jsx values

• react → classic React transform
• react-jsx → modern React transform
• preserve → keep JSX for Babel or another tool

Debug checklist

1. Is the file named .tsx?
2. Is it inside include?
3. Is there another tsconfig.json nearby?

Why do I still get the JSX flag error even though jsx is in tsconfig.json?

Usually because the file is not part of that TypeScript project, or the editor is not using that config.

Should I use jsx: "react" or jsx: "preserve"?

If Babel transforms JSX, preserve is often best. If TypeScript handles the JSX transform itself, use react or react-jsx depending on your React setup.

Does Babel fix TypeScript editor errors?

No. Babel compiles code, but TypeScript still needs its own configuration for type checking and editor diagnostics.

Can JSX be used in a .ts file?

No. Use .tsx for files containing JSX.

How do I check which TypeScript config is being used?

Run npx tsc --showConfig and inspect the resolved settings. Also check whether your editor is using the workspace TypeScript version.

Why does the error appear only in the editor but not in the build?

Because Babel may compile successfully, while the editor's TypeScript server is using the wrong config or stale project state.

Can include cause JSX errors?

• TSConfig — controls how TypeScript reads, checks, and includes files in a project.
• JSX — the syntax used in React components that TypeScript must be configured to parse.
• TSX files — the file extension required for TypeScript files that contain JSX.
• Babel vs TypeScript — important because Babel transpilation and TypeScript type checking are separate responsibilities.
• React JSX runtime — related to choosing between react and react-jsx.
• TypeScript project boundaries — helps explain why include, exclude, and nested configs affect editor behavior.
• Module resolution — useful when debugging broader TypeScript setup issues.
• Editor TypeScript server — relevant because stale or incorrect editor state often causes config-related errors.